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 route at /opportunities/new is a thin server shell: it resolves the partner session and hands clerkUserId to NewOpportunityForm, the client component that submits to the registerOpportunity server action in lib/actions/opportunities.ts via React useActionState.

Why the split: the form needs the Clerk user id to namespace its saved draft. Reading it server-side rather than calling useUser() in the client keeps the route free of Clerk context — a Clerk hook here makes the page unprerenderable and fails next build whenever no valid publishable key is present at build time.

Draft persistence and the Reset button#

Fields are controlled, held by useOpportunityDraft over the pure lib/opportunity-draft.ts.

This exists because React 19 automatically resets uncontrolled <form action={fn}> elements once the action settles. The fields previously read only defaultValue, so a single validation error — one malformed email — wiped the entire registration, checkbox groups included.

Storage is localStorage, not sessionStorage: the latter is destroyed when the tab closes, which would fail the main case worth protecting. The DRAFT_TTL_MS (7 days) bounds the staleness localStorage would otherwise allow, and the key is namespaced per Clerk user (pm:draft:opportunity:new:<userId>) so a shared machine never restores one partner's draft into another's form. Every payload carries a version; a mismatch discards rather than hydrates a stale shape. All storage access is wrapped in try/catch (Safari private mode throws on write) and degrades to in-memory state.

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, plus Expected ARR, 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.

Expected ARR became optional because partners routinely do not know the budget at registration. opportunities.expected_arr_usd dropped its NOT NULL constraint (a db:push step recorded in PENDING_TASKS.md §11). An untouched number input submits "", which resolves to null — deliberately distinct from a stored 0, since "unknown budget" and "zero budget" are different facts. Every read surface renders unknown as an em dash via formatArrUsd in lib/format.ts, admin aggregates COALESCE to 0, and the SF upsert omits mt_Budget__c entirely rather than sending null.

Required-field convention: the form carries no (optional) labelling anywhere. A single legend — "Fields marked * are required." — sits above the first section, and requirement is signalled only by the * marker.

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";

All of the above — plus USE_CASES, COMPETING_PRODUCTS, and SPECIALIZATIONS — are exported from lib/constants/partner-forms.ts as the single source. OpportunitySchema, UpdateStageSchema, OpportunityFields, and StageUpdateForm all import them, so the form and its validation cannot drift.

DEAL_STAGES was previously duplicated: a six-value list inside OpportunityFields and a four-value list inside StageUpdateForm. A deal registered at Discovery or POC/Pilot could therefore never be re-staged. One exported constant now feeds all three consumers.

The use-case and competition taxonomy

Both checkbox groups carry business-approved options rather than the generic AI-automation list they originally shipped with. Because both serialise to Salesforce as free text (below), the lists can be revised without a migration — historical deals keep whatever strings they were saved with and render verbatim.

USE_CASES is the business-approved list (2026-08-11), superseding the earlier DDR-derived draft, in approved order: Agentic AI Remediation · Compliance Readiness · Dynamic Risk Prioritization · DPDP Compliance · Data Lineage and Flow · On-Prem Support · Insider Data Risk & Behaviour Detection · Endpoint Data Visibility & DLP Enrichment · AI Asset and Risk Intelligence · Real-Time AI Interaction Control · AI-Aware Discovery and Contextual Intelligence · Database Activity Monitoring (DAM) · Other.

COMPETING_PRODUCTS is likewise the business-approved list (2026-08-11): Forcepoint · Sentra · Securiti.ai · Varonis · Guardium · Microsoft Purview · Symmetry · None / Greenfield · Other. (The approved list named Sentra twice — deduplicated. "None / Greenfield" and "Other" are kept as terminators so a partner facing no competitor, or an unlisted one, has an honest answer.) A unit test pins both lists exactly, so a drive-by edit fails the suite.

SPECIALIZATIONS (partner profile, rendered as chips on the public directory) is a different axis — the partner's delivery capability, not the customer's use case — so it has its own list.

No Salesforce migration was needed. Both fields serialise to SF as free text (mt_Use_Case_Details__c, a 255-char TextArea, and the Lead Description), not picklists. Historical rows keep whatever strings they were saved with and render verbatim; only the selectable options changed.

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.

PartnerAccountId degradation (seen live 2026-08-11): the org rejects Lead.PartnerAccountId for the integration user (INVALID_FIELD_FOR_INSERT_UPDATE — no Edit FLS, or platform-managed like IsPartner). Rather than losing the entire Lead over one attribution lookup, the upsert retries once without it (lib/sf/error-fields.ts, strictly limited to an explicit droppable list) and logs the dropped fields; attribution still flows via mt_Partner_Company_Name__c, which the same response did not reject. If the SF admin grants Edit FLS on the field (PENDING_TASKS §14), later re-upserts populate the standard lookup automatically.

Editing a registered deal#

Once a deal exists, the updateOpportunity server action (same file) lets it be completed — not rewritten. Editing is append-only: a field that was saved with a value is locked, while a field still empty stays fillable, so a deal can be enriched over time without any submitted fact ever changing. 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. Compose the SET clause — buildUpdateSet(row, parsed, { bypassLocks: clearance.ok }) decides what may actually be written. See Append-only field locking.
6. Update — apply only the surviving columns; blank optional fields persist as null. lastActivityAt + updatedAt are bumped (resetting the inactivity clock).
7. 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) and the post-filter values — pushing the raw submission would let a rejected overwrite reach the Lead anyway. If the Lead had no sfLeadId yet and the upsert now returns one, it's written back.
8. Audit — opportunity.updated with metadata.bySuperAdmin set when a super admin edited a deal they didn't register, plus a separate opportunity.admin_field_override entry when a super admin changed an already-submitted value.
9. Revalidate — the detail page and list; returns { success: true }, plus ignoredFields when locked fields were dropped (no redirect — the form collapses in place and the refreshed row renders above it).

Append-only field locking#

lib/opportunity-fields.ts is the single source for what is editable. It is a plain module, not "use server" — action files may only export async functions, so a sync helper exported from one would pass tsc, run in dev, then fail the production build.

What locks. lockedFields(row) walks LOCKABLE_FIELDS and locks any scalar where isFieldPopulated is true. Zero counts as an answer; null, undefined, "", whitespace, and [] do not.

What never locks.

• dealStage — a progression, owned by updateDealStage.
• notes — an append surface; the opportunity_notes timeline already exists for history.

Multi-selects (primaryUseCases, competingProducts) lock per option: an already-chosen option renders checked and disabled while unchosen options stay selectable. Server-side, mergeMulti computes persisted ∪ submitted, so additions land and attempted removals are ignored.

Enforcement is server-side. buildUpdateSet drops locked columns from the SET clause entirely, so a forged POST cannot overwrite a submitted fact regardless of what the request body contained. The read-only inputs are a convenience, never the boundary.

Partial success, not failure. A request touching a locked field still saves its legitimate portion and returns the rejected names in ignoredFields, surfaced as a non-blocking notice. A locked field resubmitted with its current value is a no-op, not a rejection.

Accessibility. Locked scalars render readOnly rather than disabled — a disabled field is dropped from FormData and removed from the accessibility tree. <select> cannot be readOnly, so a locked one is disabled and shadowed by a hidden input carrying its value; the same trick re-supplies locked checkbox options. All locked controls point aria-describedby at one shared explainer: "Submitted values cannot be changed. Contact your partner manager to correct an error."

Super-admin override. When getSuperAdminClearance().ok, locks are bypassed and the edit panel renders an explicit Admin override banner. The UI condition and the action's bypassLocks are the same clearance.ok expression, so the UI can never display locks the server does not enforce. Every overridden field is written to activity_log as opportunity.admin_field_override with a { field: [before, after] } diff. Partner-org admins get no override — the boundary stays creator-or-Matters.AI-super-admin.

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 "unique"; vocabulary unique | duplicate. Deduplication is enforced pre-insert — registerOpportunity rejects a registration when a matching non-cancelled/non-rejected deal for the same customer already exists — so every row that actually persists is "unique", which is why the column default matches the only value the writer sets.

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 (COALESCE(SUM(expectedArrUsd), 0), rendered in $k — the COALESCE matters now that ARR is nullable).
• 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.
• A Complete column and an Incomplete filter chip (below).

Completeness column#

Field-level locking makes "which deals still need qualification detail?" an operationally useful question — internal staff need to see which registrations are missing enrichment so they can chase the partner.

The column shows n/10: how many of the ten OPTIONAL_FIELDS are populated. The denominator comes from the same exported list the locking logic uses, so the listing and the edit form cannot disagree about what counts as filled. The count is a SQL CASE expression added to the existing select, so it costs no extra round trip and transfers no extra columns. Text columns count as blank when NULL or ''; numeric columns only when NULL.

The ?completeness=incomplete chip narrows the list to deals with any unfilled optional field. It toggles independently of the status chips and survives search and pagination.

Precedence: the predicate is an OR chain, explicitly parenthesised as a whole. AND binds tighter than OR in SQL, so an unwrapped chain would leak out of the surrounding and() and match rows the status filter had excluded.

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.

Deal extension (30-day)#

A partner can request a 30-day extension on a deal's expectedCloseDate, which an internal reviewer grants. Two timestamp columns back it: extensionRequestedAt and extensionGrantedAt.

Partner side — requestExtension(opportunityId) in lib/actions/opportunities.ts: requirePartnerSession(), org-ownership check, refuse if the deal is cancelled, then stamp extensionRequestedAt. Surfaced by the ExtensionCard in the deal-detail aside, which renders one of three states — request (a button), pending (after a request), or granted (with the new close date).

Admin side — grantExtension(opportunityId) in lib/actions/admin.ts: requireAdminWriteSession(), requires a pending extensionRequestedAt and a non-cancelled deal, then pushes expectedCloseDate out 30 days and stamps extensionGrantedAt. It re-asserts extensionRequestedAt IS NOT NULL AND extensionGrantedAt IS NULL in the UPDATE ... WHERE so a double-submit can't grant twice (which would push the date +60 days and re-fire the email). It then notifies the partner (deal_status), emails the submitter via sendExtensionGrantedEmail, and audits. Surfaced as a Grant button in the Extension column of /admin/opportunities.

Both the in-portal notification link and the revalidatePath target the deal detail route by opportunities.id (a UUID) — not portalLeadId, which is what the route resolves by; using the wrong id would 404 the notification click.

Email notifications#

Rendered through @matters/email (see Email Design System) by the pure builders in lib/email-templates.ts, 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.

Internal alerts. These two templates are the partner-facing emails. Deal registration additionally fires the deal.registered event through the Notification Engine, which alerts Matters.AI staff over in-app, email, and Slack according to super-admin-configured routing — closing the "notify the internal channel/sales team of new registrations" requirement WEB-1 had carried unmet since 2026-06-01. Extension requests, MDF submissions, and failed Salesforce sync retries route the same way.

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.
• Append-only writes: already-populated fields are dropped from the SET clause server-side, so a forged POST cannot overwrite a submitted fact. Multi-selects merge additively. Only a super admin bypasses, and every bypass is audited with a before/after diff.
• Draft isolation: the registration draft key is namespaced per Clerk user, so a shared machine never restores one partner's entry into another's form.
• 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