This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/gitgram/web/utils/talentUnlock.ts
caelum0x 757cd50d12 feat(talent): wire recruiter candidate-unlock UI to Creem revenue path
The recruiter placement/unlock backend was end-to-end (routes,
talentBillingService, Creem checkout + signed webhook settlement) but had
no frontend, so recruiters literally could not pay. This closes the only
fully dead-ended money surface.

Web (gitgram/web):
- talentGraphService: add listUnlocks, requestUnlock (idempotent, optional
  placement success-fee), and getCandidateContact mapping the existing
  owner-gated backend routes, with typed placement/contact envelopes.
- utils/talentUnlock: pure gating helpers (deriveUnlockState, findPlacement,
  interpretUnlockResult, formatFee) so the owner-only logic is unit tested
  without rendering.
- talent-network page: owner-only "Unlock candidate" action on each match
  card — opens the Creem checkout, reveals contact + full evidence once the
  entitlement is paid (poll via "check payment" and on-return via query
  params), with not-owner / pending / unlocked / already-unlocked states.

Backend (gitgram/backend):
- talentBillingController: point the checkout successUrl at the real
  /talent-network page (with opportunity + unlocked params) instead of a
  non-existent /talent/opportunities route, so payment return is not a 404.

Tests: unit-test the three service methods (idempotency header, success-fee
body, already-unlocked, 402-when-unpaid, id encoding) and the gating helper
(not-owner/unlockable/pending/unlocked, checkout-vs-reveal). 21 new tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-06 10:30:06 +03:00

68 lines
2.5 KiB
TypeScript

/**
* Pure helpers for the recruiter candidate-unlock revenue flow.
*
* These keep the gating/error logic out of the talent-network page component so
* it can be unit tested without rendering. The backend
* (talentBillingController) is the source of truth for authorization; these
* helpers only decide what the owner-facing UI should show.
*/
import type { RequestUnlockResult, TalentPlacement } from '@/services/talentGraphService'
/**
* UI state for a single candidate's unlock action:
* - `not-owner` — the viewer does not own the opportunity; no unlock action.
* - `unlockable` — owner, no entitlement yet; the paid unlock can be started.
* - `pending` — owner, a checkout is open but not yet settled.
* - `unlocked` — owner, the entitlement is paid; contact can be revealed.
*/
export type UnlockState = 'not-owner' | 'unlockable' | 'pending' | 'unlocked'
/** Finds the recruiter's placement entitlement for a candidate, if any. */
export function findPlacement(
placements: ReadonlyArray<TalentPlacement>,
candidateId: string,
): TalentPlacement | null {
return placements.find((placement) => placement.candidateId === candidateId) ?? null
}
/**
* Derives the unlock UI state for a candidate. Only the opportunity owner may
* unlock; a `paid` entitlement means unlocked, a `pending` one means a checkout
* is in flight, and anything else (including no entitlement) is unlockable.
*/
export function deriveUnlockState(params: {
isOwner: boolean
placement?: Pick<TalentPlacement, 'status'> | null
}): UnlockState {
if (!params.isOwner) return 'not-owner'
switch (params.placement?.status) {
case 'paid':
return 'unlocked'
case 'pending':
return 'pending'
default:
return 'unlockable'
}
}
/**
* Interprets a `requestUnlock` response: either the entitlement is already paid
* (reveal now) or a checkout URL must be opened to collect payment.
*/
export function interpretUnlockResult(result: RequestUnlockResult): {
action: 'reveal' | 'checkout'
checkoutUrl: string | null
} {
if (result.alreadyUnlocked || !result.checkoutUrl) {
return { action: 'reveal', checkoutUrl: null }
}
return { action: 'checkout', checkoutUrl: result.checkoutUrl }
}
/** Formats a fee in cents as a plain currency string (e.g. 4900 → "$49.00"). */
export function formatFee(feeCents: number, currency = 'usd'): string {
const amount = (feeCents / 100).toFixed(2)
const symbol = currency.toLowerCase() === 'usd' ? '$' : ''
return symbol ? `${symbol}${amount}` : `${amount} ${currency.toUpperCase()}`
}