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/backend/tests/unit/talentBilling.test.ts
caelum0x 72c0f8c12c feat(talent): wire recruiter placement/unlock revenue via Creem
The talent graph's recruiter monetization was designed (Opportunity → Pilot →
Proof funnel) but never wired to charge. This adds the placement/candidate-unlock
revenue engine on top of the existing talent graph, charged through Creem (a
merchant-of-record with Turkey-based-seller payout support — the portfolio
standard used by bidstage/CalDesk), not Polar/Stripe.

Revenue gate: a recruiter (opportunity owner) unlocks a matched candidate's
contact + full evidence. Gating mirrors the referral gate (owner-only, no
self-unlock, candidate must have real matching evidence). The fee is charged via
a Creem checkout whose custom_price is the exact computed fee, and settled by the
signed checkout.completed webhook, which records the entitlement + receipt.

- Fee math (pure, configurable): flat unlock access fee (TALENT_UNLOCK_FEE_CENTS,
  default $49) or a percentage placement success fee (rate + min/max clamps) when
  a placement amount is supplied.
- New TalentPlacement model + migration: entitlement/receipt with a compound
  unique key (opportunity, candidate, recruiter) for charge idempotency and a
  unique providerOrderId; provider defaults to creem.
- Creem adapter (createCreemCheckout) mirroring the reviewed bidstage lib/creem.ts,
  and a signed Creem webhook route (HMAC-SHA256, timing-safe) that settles
  placements. Amount is revalidated against the quoted fee before unlocking.
- Routes: POST/GET /talent-graph/opportunities/:id/unlocks and gated
  GET .../candidates/:candidateId/contact (402 until paid).
- Errors.paymentRequired (402) helper.
- Tests: fee math, gating, charge idempotency, and the signed webhook settlement
  path (75 tests). Secrets are env-only (CREEM_API_KEY, CREEM_WEBHOOK_SECRET,
  CREEM_PRODUCT_ID) — none committed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-08-26 21:31:07 +03:00

419 lines
15 KiB
TypeScript

/**
* Unit tests for the talent-graph placement / candidate-unlock revenue engine
* (talentBillingService). Covers the three load-bearing concerns of a charge:
* 1. Fee math — flat unlock fee + percentage placement success fee (rounding,
* floor/ceiling clamps, invalid inputs).
* 2. Gating — only the opportunity owner can unlock, no self-unlock, and the
* candidate must have real matching evidence.
* 3. Idempotency — a paid entitlement never re-charges, a pending entitlement
* is reused, and settlement is a no-op once paid.
*
* Everything runs in-memory against injected fakes (db / matcher / checkout), so
* no live Postgres or Polar is required — the same pattern as the matcher tests.
*/
import {
getUnlockFeeCents,
computePlacementFeeCents,
resolvePlacementFee,
requestCandidateUnlock,
settlePlacementOrder,
isCandidateUnlocked,
DEFAULT_UNLOCK_FEE_CENTS,
type BillingDb,
} from '../../src/services/talentBillingService';
// ---------------------------------------------------------------------------
// In-memory fakes
// ---------------------------------------------------------------------------
type PlacementRow = {
id: string;
opportunityId: string;
candidateId: string;
recruiterId: string;
feeCents: number;
feeModel: string;
status: string;
checkoutId?: string | null;
polarOrderId?: string | null;
paidAt?: Date | null;
};
function makeFakeDb(opportunity: any, seedPlacements: PlacementRow[] = []) {
const placements = [...seedPlacements];
let counter = 0;
const db: BillingDb = {
talentOpportunity: {
findUnique: async ({ where }: any) =>
opportunity && opportunity.id === where.id ? { ...opportunity } : null,
},
talentPlacement: {
findUnique: async ({ where }: any) => {
if (where.id) return placements.find((p) => p.id === where.id) ?? null;
const key = where.opportunityId_candidateId_recruiterId;
if (key) {
return (
placements.find(
(p) =>
p.opportunityId === key.opportunityId &&
p.candidateId === key.candidateId &&
p.recruiterId === key.recruiterId,
) ?? null
);
}
return null;
},
create: async ({ data }: any) => {
const row: PlacementRow = { id: `placement-${++counter}`, ...data };
placements.push(row);
return { ...row };
},
update: async ({ where, data }: any) => {
const row = placements.find((p) => p.id === where.id);
if (!row) throw new Error('placement not found');
Object.assign(row, data);
return { ...row };
},
},
};
return { db, placements };
}
const OPPORTUNITY = {
id: 'opp-1',
createdById: 'recruiter-1',
requiredSkills: ['typescript'],
};
function matcherWithEvidence(candidateId: string) {
return (async () => [
{ profile: { id: candidateId }, projects: [{ id: 'r1' }] },
]) as any;
}
const matcherNoEvidence = (async () => []) as any;
function fakeCheckout() {
const calls: any[] = [];
const fn = (async (input: any) => {
calls.push(input);
return {
id: `checkout-${calls.length}`,
checkoutUrl: `https://checkout.creem.io/session-${calls.length}`,
status: 'pending' as const,
};
}) as any;
return { fn, calls };
}
const baseParams = {
recruiterId: 'recruiter-1',
opportunityId: 'opp-1',
candidateId: 'candidate-1',
recruiterEmail: 'recruiter@example.com',
successUrl: 'https://app.example.com/return',
};
// ---------------------------------------------------------------------------
// Fee math
// ---------------------------------------------------------------------------
describe('fee math', () => {
const ENV_KEYS = [
'TALENT_UNLOCK_FEE_CENTS',
'TALENT_PLACEMENT_FEE_RATE',
'TALENT_PLACEMENT_FEE_MIN_CENTS',
'TALENT_PLACEMENT_FEE_MAX_CENTS',
];
const saved: Record<string, string | undefined> = {};
beforeEach(() => {
for (const key of ENV_KEYS) {
saved[key] = process.env[key];
delete process.env[key];
}
});
afterEach(() => {
for (const key of ENV_KEYS) {
if (saved[key] === undefined) delete process.env[key];
else process.env[key] = saved[key];
}
});
it('returns the default flat unlock fee', () => {
expect(getUnlockFeeCents()).toBe(DEFAULT_UNLOCK_FEE_CENTS);
expect(getUnlockFeeCents()).toBe(4900);
});
it('honours a valid TALENT_UNLOCK_FEE_CENTS override', () => {
process.env.TALENT_UNLOCK_FEE_CENTS = '9900';
expect(getUnlockFeeCents()).toBe(9900);
});
it('falls back to the default when the env override is invalid', () => {
process.env.TALENT_UNLOCK_FEE_CENTS = 'not-a-number';
expect(getUnlockFeeCents()).toBe(DEFAULT_UNLOCK_FEE_CENTS);
process.env.TALENT_UNLOCK_FEE_CENTS = '-5';
expect(getUnlockFeeCents()).toBe(DEFAULT_UNLOCK_FEE_CENTS);
});
it('computes a percentage placement fee (10% of $10,000 = $1,000)', () => {
// 10% default rate, amount 1,000,000 cents ($10k) -> 100,000 cents ($1k)
expect(computePlacementFeeCents(1_000_000)).toBe(100_000);
});
it('rounds the computed fee half-up to the nearest cent', () => {
// 3333 * 0.10 = 333.3 -> 333 ; 3335 * 0.10 = 333.5 -> 334
expect(computePlacementFeeCents(3333, { rate: 0.1, minCents: 1, maxCents: 10_000_000 })).toBe(333);
expect(computePlacementFeeCents(3335, { rate: 0.1, minCents: 1, maxCents: 10_000_000 })).toBe(334);
});
it('applies the floor when the raw fee is below the minimum', () => {
// 1,000 * 0.10 = 100, floored to 4,900
expect(computePlacementFeeCents(1_000)).toBe(4_900);
});
it('applies the ceiling when the raw fee is above the maximum', () => {
// 100,000,000 * 0.10 = 10,000,000, capped to 2,000,000
expect(computePlacementFeeCents(100_000_000)).toBe(2_000_000);
});
it('rejects non-positive or non-integer placement amounts', () => {
expect(() => computePlacementFeeCents(0)).toThrow();
expect(() => computePlacementFeeCents(-100)).toThrow();
expect(() => computePlacementFeeCents(12.5)).toThrow();
});
it('resolvePlacementFee selects the unlock model without an amount', () => {
expect(resolvePlacementFee({})).toEqual({ feeCents: DEFAULT_UNLOCK_FEE_CENTS, feeModel: 'unlock' });
});
it('resolvePlacementFee selects the placement model with an amount', () => {
expect(resolvePlacementFee({ placementAmountCents: 1_000_000 })).toEqual({
feeCents: 100_000,
feeModel: 'placement',
});
});
});
// ---------------------------------------------------------------------------
// Gating
// ---------------------------------------------------------------------------
describe('requestCandidateUnlock gating', () => {
it('rejects a recruiter unlocking their own profile', async () => {
const { db } = makeFakeDb(OPPORTUNITY);
const checkout = fakeCheckout();
await expect(
requestCandidateUnlock(
{ ...baseParams, candidateId: 'recruiter-1' },
{ db, matcher: matcherWithEvidence('recruiter-1'), createCheckout: checkout.fn },
),
).rejects.toThrow(/cannot unlock their own/i);
expect(checkout.calls).toHaveLength(0);
});
it('rejects when the opportunity does not exist', async () => {
const { db } = makeFakeDb(null);
const checkout = fakeCheckout();
await expect(
requestCandidateUnlock(baseParams, {
db,
matcher: matcherWithEvidence('candidate-1'),
createCheckout: checkout.fn,
}),
).rejects.toThrow(/not found/i);
expect(checkout.calls).toHaveLength(0);
});
it('rejects a recruiter who does not own the opportunity', async () => {
const { db } = makeFakeDb({ ...OPPORTUNITY, createdById: 'someone-else' });
const checkout = fakeCheckout();
await expect(
requestCandidateUnlock(baseParams, {
db,
matcher: matcherWithEvidence('candidate-1'),
createCheckout: checkout.fn,
}),
).rejects.toThrow(/only the opportunity owner/i);
expect(checkout.calls).toHaveLength(0);
});
it('rejects a candidate without matching evidence', async () => {
const { db, placements } = makeFakeDb(OPPORTUNITY);
const checkout = fakeCheckout();
await expect(
requestCandidateUnlock(baseParams, { db, matcher: matcherNoEvidence, createCheckout: checkout.fn }),
).rejects.toThrow(/evidence/i);
expect(checkout.calls).toHaveLength(0);
expect(placements).toHaveLength(0);
});
});
// ---------------------------------------------------------------------------
// Happy path + idempotency of the charge
// ---------------------------------------------------------------------------
describe('requestCandidateUnlock charge + idempotency', () => {
it('opens a checkout for a valid unlock and records a pending entitlement', async () => {
const { db, placements } = makeFakeDb(OPPORTUNITY);
const checkout = fakeCheckout();
const result = await requestCandidateUnlock(baseParams, {
db,
matcher: matcherWithEvidence('candidate-1'),
createCheckout: checkout.fn,
});
expect(result.alreadyUnlocked).toBe(false);
expect(result.checkoutUrl).toBe('https://checkout.creem.io/session-1');
expect(checkout.calls).toHaveLength(1);
expect(placements).toHaveLength(1);
expect(placements[0].status).toBe('pending');
expect(placements[0].feeCents).toBe(DEFAULT_UNLOCK_FEE_CENTS);
expect(placements[0].feeModel).toBe('unlock');
expect(placements[0].checkoutId).toBe('checkout-1');
// Creem custom_price is charged the exact computed fee.
expect(checkout.calls[0].amountCents).toBe(DEFAULT_UNLOCK_FEE_CENTS);
expect(checkout.calls[0].requestId).toBe(placements[0].id);
// metadata carries the placement id for webhook settlement
expect(checkout.calls[0].metadata.placementId).toBe(placements[0].id);
expect(checkout.calls[0].metadata.kind).toBe('talent_placement');
});
it('uses the placement success-fee model when an amount is supplied', async () => {
const { db, placements } = makeFakeDb(OPPORTUNITY);
const checkout = fakeCheckout();
await requestCandidateUnlock(
{ ...baseParams, placementAmountCents: 1_000_000 },
{ db, matcher: matcherWithEvidence('candidate-1'), createCheckout: checkout.fn },
);
expect(placements[0].feeModel).toBe('placement');
expect(placements[0].feeCents).toBe(100_000);
});
it('does not re-charge when the candidate is already unlocked (paid)', async () => {
const paid: PlacementRow = {
id: 'placement-existing',
opportunityId: 'opp-1',
candidateId: 'candidate-1',
recruiterId: 'recruiter-1',
feeCents: 4900,
feeModel: 'unlock',
status: 'paid',
paidAt: new Date(),
};
const { db, placements } = makeFakeDb(OPPORTUNITY, [paid]);
const checkout = fakeCheckout();
const result = await requestCandidateUnlock(baseParams, {
db,
matcher: matcherWithEvidence('candidate-1'),
createCheckout: checkout.fn,
});
expect(result.alreadyUnlocked).toBe(true);
expect(result.checkoutUrl).toBeNull();
expect(checkout.calls).toHaveLength(0);
expect(placements).toHaveLength(1);
});
it('reuses a pending entitlement instead of creating a second one', async () => {
const pending: PlacementRow = {
id: 'placement-pending',
opportunityId: 'opp-1',
candidateId: 'candidate-1',
recruiterId: 'recruiter-1',
feeCents: 4900,
feeModel: 'unlock',
status: 'pending',
};
const { db, placements } = makeFakeDb(OPPORTUNITY, [pending]);
const checkout = fakeCheckout();
const result = await requestCandidateUnlock(baseParams, {
db,
matcher: matcherWithEvidence('candidate-1'),
createCheckout: checkout.fn,
});
expect(result.alreadyUnlocked).toBe(false);
expect(placements).toHaveLength(1); // reused, not duplicated
expect(result.placement.id).toBe('placement-pending');
expect(checkout.calls).toHaveLength(1);
});
});
// ---------------------------------------------------------------------------
// Settlement + entitlement
// ---------------------------------------------------------------------------
describe('settlePlacementOrder + isCandidateUnlocked', () => {
function seedPending(): { db: BillingDb; placements: PlacementRow[] } {
return makeFakeDb(OPPORTUNITY, [
{
id: 'placement-1',
opportunityId: 'opp-1',
candidateId: 'candidate-1',
recruiterId: 'recruiter-1',
feeCents: 4900,
feeModel: 'unlock',
status: 'pending',
},
]);
}
it('marks a pending placement paid and stamps the receipt', async () => {
const { db, placements } = seedPending();
const result = await settlePlacementOrder(
{ placementId: 'placement-1', providerOrderId: 'order-abc', amountCents: 4900 },
{ db },
);
expect(result).toEqual({ settled: true, alreadyPaid: false });
expect(placements[0].status).toBe('paid');
expect(placements[0].providerOrderId).toBe('order-abc');
expect(placements[0].paidAt).toBeInstanceOf(Date);
});
it('is idempotent — replaying the order for a paid placement is a no-op', async () => {
const { db, placements } = seedPending();
await settlePlacementOrder({ placementId: 'placement-1', providerOrderId: 'order-abc' }, { db });
const firstPaidAt = placements[0].paidAt;
const replay = await settlePlacementOrder(
{ placementId: 'placement-1', providerOrderId: 'order-duplicate' },
{ db },
);
expect(replay).toEqual({ settled: false, alreadyPaid: true });
expect(placements[0].providerOrderId).toBe('order-abc'); // unchanged
expect(placements[0].paidAt).toBe(firstPaidAt);
});
it('refuses to settle when the paid amount does not match the quoted fee', async () => {
const { db, placements } = seedPending();
const result = await settlePlacementOrder(
{ placementId: 'placement-1', providerOrderId: 'order-abc', amountCents: 100 },
{ db },
);
expect(result).toEqual({ settled: false, alreadyPaid: false, amountMismatch: true });
expect(placements[0].status).toBe('pending');
expect(placements[0].providerOrderId).toBeUndefined();
});
it('reports a missing placement without throwing', async () => {
const { db } = seedPending();
const result = await settlePlacementOrder({ placementId: 'nope', providerOrderId: 'order-x' }, { db });
expect(result).toEqual({ settled: false, alreadyPaid: false });
});
it('isCandidateUnlocked is true only after settlement', async () => {
const { db } = seedPending();
expect(await isCandidateUnlocked('opp-1', 'candidate-1', 'recruiter-1', db)).toBe(false);
await settlePlacementOrder({ placementId: 'placement-1', providerOrderId: 'order-abc' }, { db });
expect(await isCandidateUnlocked('opp-1', 'candidate-1', 'recruiter-1', db)).toBe(true);
expect(await isCandidateUnlocked('opp-1', 'other', 'recruiter-1', db)).toBe(false);
});
});