diff --git a/SALES.md b/SALES.md index 3fe8f4e..203c508 100644 --- a/SALES.md +++ b/SALES.md @@ -593,3 +593,53 @@ close-date/customer-type fields when their labels cannot be resolved. Default field IDs apply only to the default report. Forecast does not replace the recognised-revenue customer matrices. Existing incomplete-source and currency notices apply. Deploy this API before the companion UI; no migration is required. + +## PM-6783: goods-sold date/offering filters and booking costs + +`GET /sales-dashboard/payments` now returns both `customerPayments` and +`customerBookingCosts` with identical complete customer series and month buckets. +Booking Cost is the existing member-payment amount (`gross_amount`, falling back +to `total_amount`) plus `finance.payment.challenge_fee`, counted once for the +latest payment version. Cancelled payments remain excluded. Zero fees and +negative adjustments are preserved; a missing fee makes that customer/month's +booking cost `null` and adds a notice that totals include known values only. +No payment is inferred from a fee rate or from a customer's revenue. + +`startDate` is inclusive and `endDate` is exclusive, both in UTC and applied at +payment-event precision before aggregation. Existing validation limits ranges +to 732 days. The UI converts the inclusive To date to next-day midnight. + +Repeat `offeringType` for OR selections; omit it for ALL. Offerings resolve by the +effective billing-account ID, using the existing payment-account precedence and +challenge-account fallback, through Salesforce: + +- `Topcoder_Billing_Account__c.TopCoder_Billing_Account_Id__c` +- `Opportunity__r.Engagement_Offering_Type__c` and `Opportunity__r.Name` + +These are exact ID lookups, without a close-date restriction or customer-name +matching. The client validates numeric IDs, queries batches of 200, caches results +for one minute, and rejects incomplete/conflicting results. Known offering labels +are normalized like customer revenue (including TopGear Ops → TopGear and the +existing two blank-offering corrections). Other recorded offerings remain +available. Missing accounts, opportunity links and categories are **Unknown**; +ALL includes them and Unknown can also be selected explicitly. + +The query first obtains eligible billing-account IDs alongside the unfiltered +payment aggregates. After resolving the selected offerings, it reruns the +parameterized SQL with the matching IDs, so filtering precedes type/customer +sums, rankings and distinct member counts. `filterOptions.offeringType` retains +the full choices for the date/portal scope, even when a selection matches no rows. +An empty account selection matches nothing; it never becomes ALL. Both matrices +retain the existing Sales/Reports portal scope and TaaS/TopGear-payment exclusions. +The separate TaaS report does not perform offering lookups. + +If Salesforce fails, unfiltered member/booking totals remain available with an +explicit offering-unavailable notice. A selected offering fails the request +instead of returning unfiltered totals. Existing report OAuth configuration and +Salesforce object/field read permissions must permit the lookup above. + +Deploy this API change before the PM-6783 platform-ui change. No database migration +or new configuration variables are required. Validation covers real PostgreSQL +aggregation, inclusive/exclusive/leap-day boundaries, latest/cancelled versions, +multiple account selections, unknown links/fees, negative/zero fees, customer +scope, Salesforce ID validation/batching/cache, and upstream failure handling. diff --git a/sql/reports/dashboard/sales-payments.sql b/sql/reports/dashboard/sales-payments.sql index 27a1244..7e2bc58 100644 --- a/sql/reports/dashboard/sales-payments.sql +++ b/sql/reports/dashboard/sales-payments.sql @@ -1,5 +1,7 @@ -- $1/$2 inclusive/exclusive UTC bounds; $3 restricts to customer work for Sales. -- $4 selects TaaS only; false selects non-TaaS Topcoder payments. +-- $5 optionally selects effective billing-account IDs resolved from Salesforce offerings. +-- NULL means ALL; an empty array matches none; unknown includes unlinked accounts. -- Exclude TaaS, internal Topcoder and unlinked payments BEFORE any sums or rankings. -- Uses the established dashboard payment version, category and customer-label rules. WITH bounds AS ( @@ -27,6 +29,8 @@ payment_events AS MATERIALIZED ( END AS payment_type, NULLIF(BTRIM(cl.name), '') AS client_name, COALESCE(p.gross_amount, p.total_amount, 0) AS amount, + p.challenge_fee, + COALESCE(payment_ba.id::text, challenge_ba.id::text, 'unknown') AS billing_account_id, NULLIF(TRIM(cl.id), '') AS customer_id, NULLIF(TRIM(CASE WHEN w.category::text = 'TAAS_PAYMENT' @@ -66,7 +70,7 @@ payment_events AS MATERIALIZED ( AND NULLIF(TRIM(w.winner_id), '') IS NOT NULL AND w.category::text IS DISTINCT FROM 'TOPGEAR_PAYMENT' ), -selected_events AS ( +scoped_events AS ( SELECT pe.* FROM payment_events pe CROSS JOIN bounds b @@ -80,11 +84,17 @@ selected_events AS ( AND LOWER(pe.client_name) <> 'topcoder' AND LOWER(COALESCE(pe.customer_label, '')) NOT IN ('topcoder', 'taas') )) +), +selected_events AS ( + SELECT * FROM scoped_events + WHERE $5::text[] IS NULL OR billing_account_id = ANY($5::text[]) ) SELECT TO_CHAR(DATE_TRUNC('month', activity_at), 'YYYY-MM-01') AS month, CASE WHEN GROUPING(payment_type) = 0 THEN 'type' ELSE 'customer' END AS kind, payment_type, customer_id, customer_label, - SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members + SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members, + CASE WHEN COUNT(challenge_fee) = COUNT(*) THEN SUM(amount + challenge_fee) END AS booking_amount, + NULL::text AS billing_account_id FROM selected_events GROUP BY GROUPING SETS ( (DATE_TRUNC('month', activity_at), payment_type), @@ -93,13 +103,24 @@ GROUP BY GROUPING SETS ( UNION ALL SELECT TO_CHAR(DATE_TRUNC('quarter', activity_at), 'YYYY-MM-01') AS month, 'quarter' AS kind, payment_type, NULL AS customer_id, NULL AS customer_label, - SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members + SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members, + CASE WHEN COUNT(challenge_fee) = COUNT(*) THEN SUM(amount + challenge_fee) END AS booking_amount, + NULL::text AS billing_account_id FROM selected_events GROUP BY DATE_TRUNC('quarter', activity_at), payment_type UNION ALL SELECT NULL AS month, 'annual' AS kind, payment_type, NULL AS customer_id, NULL AS customer_label, - SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members + SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members, + CASE WHEN COUNT(challenge_fee) = COUNT(*) THEN SUM(amount + challenge_fee) END AS booking_amount, + NULL::text AS billing_account_id FROM selected_events GROUP BY payment_type +UNION ALL +-- Retain every in-range account before offering filtering so filter choices stay stable. +SELECT NULL AS month, 'billing-account' AS kind, NULL AS payment_type, + NULL AS customer_id, NULL AS customer_label, NULL AS amount, NULL AS members, + NULL AS booking_amount, billing_account_id +FROM scoped_events +GROUP BY billing_account_id ORDER BY month, kind, payment_type, customer_id, customer_label; diff --git a/src/reports/dashboard/sales-dashboard.dto.ts b/src/reports/dashboard/sales-dashboard.dto.ts index fb80271..072313a 100644 --- a/src/reports/dashboard/sales-dashboard.dto.ts +++ b/src/reports/dashboard/sales-dashboard.dto.ts @@ -167,6 +167,9 @@ export class SalesDashboardDto extends SalesCustomerRevenueDto { /** Full customer series for the payments matrix, before top-five/Other grouping. */ @ApiPropertyOptional({ type: SalesDashboardChartDto }) customerPayments?: SalesDashboardChartDto; + /** Same payment/customer scope, with challenge fees included once per payment. */ + @ApiPropertyOptional({ type: SalesDashboardChartDto }) + customerBookingCosts?: SalesDashboardChartDto; /** Offering-scoped customer matrices, including intersections with Account Category. */ @ApiPropertyOptional({ type: Object }) customerRevenueByOfferingType?: Partial< diff --git a/src/reports/dashboard/sales-dashboard.payments.spec.ts b/src/reports/dashboard/sales-dashboard.payments.spec.ts new file mode 100644 index 0000000..0287698 --- /dev/null +++ b/src/reports/dashboard/sales-dashboard.payments.spec.ts @@ -0,0 +1,166 @@ +import { BadGatewayException } from "@nestjs/common"; +import { ConfigService } from "@nestjs/config"; +import { SqlLoaderService } from "../../common/sql-loader.service"; +import { DbService } from "../../db/db.service"; +import { SalesReportsService } from "../sales/sales-reports.service"; +import { SalesDashboardSection } from "./sales-dashboard.dto"; +import { SalesDashboardService } from "./sales-dashboard.service"; + +describe("Goods sold customer payment scopes", () => { + const query = jest.fn(); + const getBillingAccountOfferings = jest.fn(); + const range = { startDate: "2028-02-15", endDate: "2028-03-01" }; + const accounts = ["1", "2", "3", "unknown"].map((billing_account_id) => ({ + kind: "billing-account", + billing_account_id, + })); + const customer = ( + month: string, + amount: string, + booking_amount: string | null, + ) => ({ + month, + amount, + booking_amount, + kind: "customer", + customer_id: "client", + customer_label: "Customer", + }); + const api = () => + new SalesDashboardService( + { query } as unknown as DbService, + new SqlLoaderService(), + { getBillingAccountOfferings } as unknown as SalesReportsService, + new ConfigService(), + ); + beforeEach(() => { + jest.resetAllMocks(); + query.mockResolvedValue([ + ...accounts, + customer("2028-02-01", "100", "125"), + ]); + getBillingAccountOfferings.mockResolvedValue( + new Map([ + ["1", "AI Training"], + ["2", "Flexible Talent"], + ]), + ); + }); + + it("exposes both measures and all offerings without changing member totals", async () => { + const result = await api().load(SalesDashboardSection.Payments, range); + expect(query).toHaveBeenCalledTimes(1); + expect( + result.customerPayments?.months[0].values['["client","Customer"]'], + ).toBe(100); + expect( + result.customerBookingCosts?.months[0].values['["client","Customer"]'], + ).toBe(125); + expect(result.customerBookingCosts?.series).toEqual( + result.customerPayments?.series, + ); + expect(result.filterOptions?.offeringType).toEqual([ + "AI Training", + "Flexible Talent", + "Unknown", + ]); + expect(result.notices).toEqual([]); + }); + + it.each([ + [ + ["AI Training", "Flexible Talent"], + ["1", "2"], + ], + [["Unknown"], ["3", "unknown"]], + [["Not present"], []], + ])( + "resolves %j to account IDs before aggregation", + async (offeringType, selected) => { + query + .mockResolvedValueOnce(accounts) + .mockResolvedValueOnce([customer("2028-02-01", "80", "100")]); + const result = await api().load(SalesDashboardSection.Payments, { + ...range, + portal: "sales", + offeringType, + }); + expect(query).toHaveBeenLastCalledWith(expect.any(String), [ + "2028-02-15T00:00:00.000Z", + "2028-03-01T00:00:00.000Z", + true, + false, + selected, + ]); + expect( + result.customerPayments?.months[0].values['["client","Customer"]'], + ).toBe(80); + expect( + result.customerBookingCosts?.months[0].values['["client","Customer"]'], + ).toBe(100); + expect(result.filterOptions?.offeringType).toEqual([ + "AI Training", + "Flexible Talent", + "Unknown", + ]); + }, + ); + + it("keeps all-payment and booking amounts available on a lookup failure, but rejects filtered requests", async () => { + getBillingAccountOfferings.mockRejectedValue( + new BadGatewayException("upstream unavailable"), + ); + const service = api(); + const result = await service.load(SalesDashboardSection.Payments, range); + expect( + result.customerBookingCosts?.months[0].values['["client","Customer"]'], + ).toBe(125); + expect(result.notices).toContain( + "Offering type details are unavailable. All payment offerings are included.", + ); + await expect( + service.load(SalesDashboardSection.Payments, { + ...range, + offeringType: ["AI Training"], + }), + ).rejects.toThrow("upstream unavailable"); + }); + + it("preserves unavailable fees, negative adjustments and zero-filled months", async () => { + query.mockResolvedValue([ + customer("2028-02-01", "100", null), + customer("2028-03-01", "-20", "-25"), + ]); + const result = await api().load(SalesDashboardSection.Payments, { + ...range, + endDate: "2028-05-01", + }); + expect( + result.customerBookingCosts?.months.map( + (month) => month.values['["client","Customer"]'], + ), + ).toEqual([null, -25, 0]); + expect(result.notices[0]).toContain("Some challenge fees are unavailable"); + }); + + it("returns empty matrices without Salesforce requests for empty data", async () => { + query.mockResolvedValue([]); + const result = await api().load(SalesDashboardSection.Payments, range); + expect(result.customerPayments?.series).toEqual([]); + expect(result.customerBookingCosts?.series).toEqual([]); + expect(getBillingAccountOfferings).not.toHaveBeenCalled(); + }); + + it("keeps TaaS independent from offering lookups and booking matrices", async () => { + const result = await api().load(SalesDashboardSection.TaasPayments, range); + expect(getBillingAccountOfferings).not.toHaveBeenCalled(); + expect(result.customerBookingCosts).toBeUndefined(); + expect(query).toHaveBeenLastCalledWith(expect.any(String), [ + "2028-02-15T00:00:00.000Z", + "2028-03-01T00:00:00.000Z", + false, + true, + null, + ]); + }); +}); diff --git a/src/reports/dashboard/sales-dashboard.service.ts b/src/reports/dashboard/sales-dashboard.service.ts index 9e07031..27c208a 100644 --- a/src/reports/dashboard/sales-dashboard.service.ts +++ b/src/reports/dashboard/sales-dashboard.service.ts @@ -54,6 +54,8 @@ type PaymentRow = { customer_id: string | null; customer_label: string | null; amount: string; + booking_amount: string | null; + billing_account_id: string | null; members: string; }; @@ -243,7 +245,12 @@ export class SalesDashboardService implements OnModuleDestroy { case SalesDashboardSection.RevenueForecast: return this.revenue(range, query, section); case SalesDashboardSection.Payments: - return this.payments(range, query.portal === "sales"); + return this.payments( + range, + query.portal === "sales", + false, + query.offeringType, + ); case SalesDashboardSection.TaasPayments: return this.payments(range, false, true); case SalesDashboardSection.Talent: @@ -698,6 +705,7 @@ export class SalesDashboardService implements OnModuleDestroy { * @param range Half-open UTC reporting range. * @param customerOnly Excludes internal Topcoder and payments without a linked customer in Sales. * @param taasOnly Selects only TaaS payments; otherwise TaaS is excluded from Topcoder payments. + * @param offeringTypes Exact offering selections (OR); empty includes all offerings, including unknowns. * @returns Payment values, distinct members per type, top-five customer chart and an ungrouped customer table. * @throws Propagates database errors. */ @@ -705,11 +713,41 @@ export class SalesDashboardService implements OnModuleDestroy { range: DashboardDateRange, customerOnly: boolean, taasOnly = false, + offeringTypes: string[] = [], ): Promise { - const rows = await this.db.query( - this.sql.load("reports/dashboard/sales-payments.sql"), - [range.startDate, range.endDate, customerOnly, taasOnly], - ); + const sql = this.sql.load("reports/dashboard/sales-payments.sql"); + const params = [range.startDate, range.endDate, customerOnly, taasOnly]; + let rows = await this.db.query(sql, [...params, null]); + const notices: string[] = []; + let offeringOptions: string[] = []; + if (!taasOnly) { + const accounts = rows + .filter((row) => row.kind === "billing-account") + .map((row) => row.billing_account_id!); + try { + const offerings = accounts.length + ? await this.sales.getBillingAccountOfferings(accounts) + : new Map(); + const label = (account: string) => offerings.get(account) ?? "Unknown"; + offeringOptions = [...new Set(accounts.map(label))].sort(); + if (offeringTypes.length) { + const selected = new Set(offeringTypes); + const billingAccounts = accounts.filter((account) => + selected.has(label(account)), + ); + rows = await this.db.query(sql, [ + ...params, + billingAccounts, + ]); + } + } catch (error) { + // Never return unfiltered amounts when an offering selection cannot be resolved. + if (offeringTypes.length) throw error; + notices.push( + "Offering type details are unavailable. All payment offerings are included.", + ); + } + } if (taasOnly) { const chart = monthlyChart(range, { id: "taas-payments", @@ -828,6 +866,13 @@ export class SalesDashboardService implements OnModuleDestroy { .sort((a, b) => a[1].localeCompare(b[1]) || a[0].localeCompare(b[0])) .map(([key, label]) => ({ key, label })), }); + const customerBookingCosts = monthlyChart(range, { + ...customerPayments, + id: "booking-customer-all", + title: "Monthly booking costs by customer", + description: + "Member payments plus challenge fees for the same customers and payment events.", + }); rows.forEach((row) => { if (row.kind === "type") { charts.forEach((chart, index) => { @@ -845,6 +890,15 @@ export class SalesDashboardService implements OnModuleDestroy { if (fullMonth) fullMonth.values[key] = (fullMonth.values[key] ?? 0) + Number(row.amount); + const bookingMonth = customerBookingCosts.months.find( + (m) => m.month === row.month, + ); + if (bookingMonth) { + bookingMonth.values[key] = + row.booking_amount == null || bookingMonth.values[key] === null + ? null + : (bookingMonth.values[key] ?? 0) + Number(row.booking_amount); + } const selected = top.some((c) => c.key === key) ? key : "other"; const month = customerChart.months.find((m) => m.month === row.month); if (month) @@ -855,7 +909,22 @@ export class SalesDashboardService implements OnModuleDestroy { return { charts: [...charts, customerChart], customerPayments, - notices: [], + customerBookingCosts, + filterOptions: { + offeringType: offeringOptions, + dealCategory: [], + customerType: [], + }, + notices: [ + ...notices, + ...(rows.some( + (row) => row.kind === "customer" && row.booking_amount === null, + ) + ? [ + "Some challenge fees are unavailable. Affected customer/month booking costs are unknown; totals include known values only.", + ] + : []), + ], }; } diff --git a/src/reports/dashboard/sales-dashboard.spec.ts b/src/reports/dashboard/sales-dashboard.spec.ts index be26a87..b01f95e 100644 --- a/src/reports/dashboard/sales-dashboard.spec.ts +++ b/src/reports/dashboard/sales-dashboard.spec.ts @@ -991,6 +991,7 @@ describe("Monthly sales dashboards", () => { new Date(range.endDate).toISOString(), false, true, + null, ]); expect(result.charts).toHaveLength(2); expect(result.charts[0].months.map((month) => month.values.taas)).toEqual( diff --git a/src/reports/dashboard/sales-dashboard.sql.spec.ts b/src/reports/dashboard/sales-dashboard.sql.spec.ts index 4305f1f..416f720 100644 --- a/src/reports/dashboard/sales-dashboard.sql.spec.ts +++ b/src/reports/dashboard/sales-dashboard.sql.spec.ts @@ -23,7 +23,7 @@ integration("Monthly sales SQL (PostgreSQL)", () => { CREATE SCHEMA projects; CREATE TABLE projects.projects (id int, "billingAccountId" int); CREATE TABLE engagements."Engagement" (id text, "projectId" text); - CREATE TABLE finance.payment (winnings_id text, version int, created_at timestamp, gross_amount numeric, total_amount numeric, billing_account text, payment_status text, challenge_markup numeric); + CREATE TABLE finance.payment (winnings_id text, version int, created_at timestamp, gross_amount numeric, total_amount numeric, billing_account text, payment_status text, challenge_markup numeric, challenge_fee numeric DEFAULT 0); CREATE TABLE finance.winnings (winning_id text, winner_id text, category text, type text, external_id text); CREATE TABLE challenges."Challenge" (id text); CREATE TABLE challenges."ChallengeBilling" ("challengeId" text, "billingAccountId" text); @@ -82,11 +82,11 @@ integration("Monthly sales SQL (PostgreSQL)", () => { it("filters customer work before type totals, distinct-member counts and customer ranking", async () => { const sales = await pool.query( sql.load("reports/dashboard/sales-payments.sql"), - [...bounds, true, false], + [...bounds, true, false, null], ); const reports = await pool.query( sql.load("reports/dashboard/sales-payments.sql"), - [...bounds, false, false], + [...bounds, false, false, null], ); const august = sales.rows.filter((r) => r.month === "2026-08-01"); expect( @@ -211,7 +211,7 @@ integration("Monthly sales SQL (PostgreSQL)", () => { `); const { rows } = await pool.query( sql.load("reports/dashboard/sales-payments.sql"), - [...bounds, true, false], + [...bounds, true, false, null], ); const labels = rows .filter((row) => row.kind === "customer") @@ -235,7 +235,7 @@ integration("Monthly sales SQL (PostgreSQL)", () => { `); const { rows } = await pool.query( sql.load("reports/dashboard/sales-payments.sql"), - [...bounds, false, true], + [...bounds, false, true, null], ); expect(rows.filter((row) => row.kind === "type")).toEqual([ expect.objectContaining({ @@ -247,7 +247,7 @@ integration("Monthly sales SQL (PostgreSQL)", () => { ]); const regular = await pool.query( sql.load("reports/dashboard/sales-payments.sql"), - [...bounds, false, false], + [...bounds, false, false, null], ); expect( regular.rows.some( @@ -271,7 +271,7 @@ integration("Monthly sales SQL (PostgreSQL)", () => { try { const result = await pool.query( sql.load("reports/dashboard/sales-payments.sql"), - ["2027-04-01T00:00:00Z", "2028-04-01T00:00:00Z", false, true], + ["2027-04-01T00:00:00Z", "2028-04-01T00:00:00Z", false, true, null], ); expect(result.rows.filter((row) => row.kind === "quarter")).toEqual([ expect.objectContaining({ @@ -303,4 +303,90 @@ integration("Monthly sales SQL (PostgreSQL)", () => { ); } }); + + it("filters billing accounts before all aggregates and adds fees once within exact UTC bounds", async () => { + const db = await pool.connect(); + await db.query("BEGIN"); + try { + await db.query(` + INSERT INTO "billing-accounts"."BillingAccount" VALUES + (90, 'customer', 'Goods customer'), (91, 'customer', 'Goods customer'), + (92, 'customer', 'Unknown fee'); + INSERT INTO finance.winnings VALUES + ('goods-a', 'm1', 'CHALLENGE_PAYMENT', 'PAYMENT', 'challenge'), + ('goods-b', 'm1', 'CHALLENGE_PAYMENT', 'PAYMENT', NULL), + ('goods-c', 'm1', 'ENGAGEMENT_PAYMENT', 'PAYMENT', NULL), + ('goods-d', 'm2', 'TASK_PAYMENT', 'PAYMENT', NULL), + ('goods-unlinked', 'm3', 'CHALLENGE_PAYMENT', 'PAYMENT', NULL), + ('goods-cancelled', 'm4', 'CHALLENGE_PAYMENT', 'PAYMENT', NULL), + ('goods-before', 'm5', 'CHALLENGE_PAYMENT', 'PAYMENT', NULL), + ('goods-after', 'm6', 'CHALLENGE_PAYMENT', 'PAYMENT', NULL); + INSERT INTO finance.payment + (winnings_id, version, created_at, gross_amount, total_amount, billing_account, payment_status, challenge_fee) + VALUES + ('goods-a', 1, '2028-02-15', 999, 999, '90', 'PAID', 999), + ('goods-a', 2, '2028-02-15', 100, 90, '00090', 'PAID', 25), + ('goods-b', 1, '2028-02-29 23:59:59.999', -20, -20, '90', 'PAID', -5), + ('goods-c', 1, '2028-02-20', 50, 50, '91', 'PAID', 0), + ('goods-d', 1, '2028-02-20', 40, 40, '92', 'OWED', NULL), + ('goods-unlinked', 1, '2028-02-20', 30, 30, NULL, 'PAID', 3), + ('goods-cancelled', 1, '2028-02-20', 999, 999, '90', 'PAID', 999), + ('goods-cancelled', 2, '2028-02-20', 999, 999, '90', 'CANCELLED', 999), + ('goods-before', 1, '2028-02-14 23:59:59.999', 999, 999, '90', 'PAID', 999), + ('goods-after', 1, '2028-03-01', 999, 999, '90', 'PAID', 999); + `); + const query = (ids: string[] | null, sales = false) => + db.query(sql.load("reports/dashboard/sales-payments.sql"), [ + "2028-02-15T00:00:00Z", + "2028-03-01T00:00:00Z", + sales, + false, + ids, + ]); + const selected = (await query(["90", "91"])).rows; + expect(selected.find((row) => row.kind === "customer")).toMatchObject({ + month: "2028-02-01", + amount: "130", + booking_amount: "150", + members: "1", + }); + expect( + selected.find( + (row) => row.kind === "type" && row.payment_type === "challenge", + ), + ).toMatchObject({ amount: "80", booking_amount: "100", members: "1" }); + expect( + selected + .filter((row) => row.kind === "billing-account") + .map((row) => row.billing_account_id) + .sort(), + ).toEqual(["90", "91", "92", "unknown"]); + expect( + (await query([])).rows.every((row) => row.kind === "billing-account"), + ).toBe(true); + expect( + (await query(["92"])).rows.find((row) => row.kind === "customer"), + ).toMatchObject({ amount: "40", booking_amount: null }); + expect( + (await query(["unknown"])).rows.find((row) => row.kind === "customer"), + ).toMatchObject({ amount: "30", booking_amount: "33" }); + const sales = (await query(null, true)).rows; + expect(sales.some((row) => row.billing_account_id === "unknown")).toBe( + false, + ); + expect( + sales + .filter((row) => row.kind === "customer") + .reduce((sum, row) => sum + Number(row.amount), 0), + ).toBe(170); + expect( + selected + .filter((row) => row.kind === "annual" || row.kind === "quarter") + .every((row) => row.members === "1"), + ).toBe(true); + } finally { + await db.query("ROLLBACK"); + db.release(); + } + }); }); diff --git a/src/reports/sales/sales-reports.service.ts b/src/reports/sales/sales-reports.service.ts index 674e3cc..80793c1 100644 --- a/src/reports/sales/sales-reports.service.ts +++ b/src/reports/sales/sales-reports.service.ts @@ -567,6 +567,13 @@ export class SalesReportsService { } } + /** Resolves current offerings by exact billing-account ID, independently of report date filters. */ + async getBillingAccountOfferings( + ids: string[], + ): Promise> { + return this.client.getBillingAccountOfferings(ids); + } + /** * Adds Pipeline's customer category by raw Opportunity ID, never by a project/customer display name. * @param report Normalized revenue snapshot. @param lookupColumns Ordered lookup IDs, direct opportunity first. @@ -605,7 +612,7 @@ export class SalesReportsService { ], rows: report.rows.map((row, index) => { const type = ids[index] - ? types.get(ids[index]!.slice(0, 15)) + ? types.get(ids[index].slice(0, 15)) : undefined; return { ...row, diff --git a/src/reports/sales/salesforce-reports.client.spec.ts b/src/reports/sales/salesforce-reports.client.spec.ts index 601a3aa..18d4644 100644 --- a/src/reports/sales/salesforce-reports.client.spec.ts +++ b/src/reports/sales/salesforce-reports.client.spec.ts @@ -142,6 +142,135 @@ describe("SalesforceReportsClient", () => { ).rejects.toBeInstanceOf(BadGatewayException); }); + it("looks up offerings by validated billing IDs, normalizes labels, and caches missing links", async () => { + await expect( + client.getBillingAccountOfferings(["unknown", "1'", "0", "1 OR 1=1"]), + ).resolves.toEqual(new Map()); + expect(request).not.toHaveBeenCalled(); + request.mockResolvedValueOnce(oauth()).mockResolvedValueOnce( + Response.json({ + done: true, + records: [ + { + TopCoder_Billing_Account_Id__c: "1", + Opportunity__r: { + Engagement_Offering_Type__c: "Crowd-Powered Outcomes", + }, + }, + { + TopCoder_Billing_Account_Id__c: "2", + Opportunity__r: { Engagement_Offering_Type__c: "TopGear Ops" }, + }, + { + TopCoder_Billing_Account_Id__c: "3", + Opportunity__r: { Name: "TopGear" }, + }, + { + TopCoder_Billing_Account_Id__c: "4", + Opportunity__r: { Name: "Multiple App Enhancement 5" }, + }, + { + TopCoder_Billing_Account_Id__c: "5", + Opportunity__r: { + Name: "TopGear", + Engagement_Offering_Type__c: "AI Training", + }, + }, + { TopCoder_Billing_Account_Id__c: "6", Opportunity__r: null }, + { + TopCoder_Billing_Account_Id__c: "99", + Opportunity__r: { Engagement_Offering_Type__c: "Do not include" }, + }, + ], + }), + ); + const ids = ["1", "2", "3", "4", "5", "6", "7", "1"]; + const expected = new Map([ + ["1", "Crowd Powered Outcomes"], + ["2", "TopGear"], + ["3", "TopGear"], + ["4", "Flexible Talent"], + ["5", "AI Training"], + ]); + await expect(client.getBillingAccountOfferings(ids)).resolves.toEqual( + expected, + ); + const q = new URL(request.mock.calls[1][0]).searchParams.get("q"); + expect(q).toBe( + "SELECT TopCoder_Billing_Account_Id__c, Opportunity__r.Engagement_Offering_Type__c, " + + "Opportunity__r.Name FROM Topcoder_Billing_Account__c WHERE TopCoder_Billing_Account_Id__c IN ('1','2','3','4','5','6','7')", + ); + await expect(client.getBillingAccountOfferings(ids)).resolves.toEqual( + expected, + ); + expect(request).toHaveBeenCalledTimes(2); + const now = Date.now(); + jest.spyOn(Date, "now").mockReturnValue(now + 61000); + request.mockResolvedValueOnce(Response.json({ done: true, records: [] })); + await expect(client.getBillingAccountOfferings(ids)).resolves.toEqual( + new Map(), + ); + expect(request).toHaveBeenCalledTimes(3); + }); + + it("batches offering requests and rejects partial or conflicting source data", async () => { + request + .mockResolvedValueOnce(oauth()) + .mockImplementation(() => + Promise.resolve(Response.json({ done: true, records: [] })), + ); + await client.getBillingAccountOfferings( + Array.from({ length: 201 }, (_, i) => String(i + 1)), + ); + expect(request).toHaveBeenCalledTimes(3); + expect( + new URL(request.mock.calls[1][0]).searchParams.get("q")?.match(/'\d+'/g), + ).toHaveLength(200); + request.mockResolvedValueOnce(Response.json({ done: false, records: [] })); + await expect(client.getBillingAccountOfferings(["300"])).rejects.toThrow( + "incomplete billing account offerings", + ); + request.mockResolvedValueOnce(Response.json({ done: true, records: null })); + await expect(client.getBillingAccountOfferings(["300"])).rejects.toThrow( + "incomplete billing account offerings", + ); + request.mockResolvedValueOnce( + Response.json({ + done: true, + records: [ + { + TopCoder_Billing_Account_Id__c: "300", + Opportunity__r: { Engagement_Offering_Type__c: "AI Training" }, + }, + { + TopCoder_Billing_Account_Id__c: "300", + Opportunity__r: { Engagement_Offering_Type__c: "Flexible Talent" }, + }, + ], + }), + ); + await expect(client.getBillingAccountOfferings(["300"])).rejects.toThrow( + "conflicting billing account offerings", + ); + }); + + it("rejects malformed offering values without exposing upstream payloads", async () => { + request.mockResolvedValueOnce(oauth()).mockResolvedValueOnce( + Response.json({ + done: true, + records: [ + { + TopCoder_Billing_Account_Id__c: "1", + Opportunity__r: { Engagement_Offering_Type__c: 42 }, + }, + ], + }), + ); + await expect(client.getBillingAccountOfferings(["1"])).rejects.toThrow( + "Salesforce returned invalid billing account offerings.", + ); + }); + it("renews expired sessions once", async () => { request .mockResolvedValueOnce(oauth()) diff --git a/src/reports/sales/salesforce-reports.client.ts b/src/reports/sales/salesforce-reports.client.ts index ccd4da2..b3ba64c 100644 --- a/src/reports/sales/salesforce-reports.client.ts +++ b/src/reports/sales/salesforce-reports.client.ts @@ -6,6 +6,7 @@ import { } from "@nestjs/common"; import { ConfigService } from "@nestjs/config"; import { setTimeout as delay } from "node:timers/promises"; +import { categoryValue } from "./sales-category.utils"; export interface SalesforceGrouping { key: string; @@ -84,6 +85,10 @@ export class SalesforceReportsClient { private session?: SalesforceSession; private authenticating?: Promise; private quotaRetryAt = 0; + private readonly billingOfferings = new Map< + string, + { expires: number; offering?: string } + >(); /** @param config Server environment configuration. Creates a lazy client; does not authenticate or throw. */ constructor(private readonly config: ConfigService) {} @@ -387,6 +392,112 @@ export class SalesforceReportsClient { return types; } + /** + * Resolves payment offerings through the billing account's linked Opportunity. + * Uses exact numeric Topcoder IDs, never customer names or opportunity close dates. + * Missing links remain unknown; malformed/incomplete or ambiguous responses fail explicitly. + * Results (including missing links) are cached for one minute and queried in batches of 200. + */ + async getBillingAccountOfferings( + ids: string[], + ): Promise> { + const unique = [...new Set(ids.filter((id) => /^[1-9]\d{0,9}$/.test(id)))]; + const now = Date.now(); + for (const [id, entry] of this.billingOfferings) { + if (entry.expires <= now) this.billingOfferings.delete(id); + } + const missing = unique.filter((id) => !this.billingOfferings.has(id)); + for (let start = 0; start < missing.length; start += 200) { + const batch = missing.slice(start, start + 200); + const query = + "SELECT TopCoder_Billing_Account_Id__c, Opportunity__r.Engagement_Offering_Type__c, " + + "Opportunity__r.Name FROM Topcoder_Billing_Account__c WHERE TopCoder_Billing_Account_Id__c IN (" + + batch.map((id) => `'${id}'`).join(",") + + ")"; + const result = await this.dataRequest<{ + done: boolean; + records: Array<{ + TopCoder_Billing_Account_Id__c: string; + Opportunity__r?: { + Engagement_Offering_Type__c?: string | null; + Name?: string; + } | null; + }>; + }>( + `query?q=${encodeURIComponent(query)}`, + {}, + "billing account offerings", + ); + if (!result || result.done !== true || !Array.isArray(result.records)) { + throw new BadGatewayException( + "Salesforce returned incomplete billing account offerings.", + ); + } + const offerings = new Map(); + for (const record of result.records) { + const id = record?.TopCoder_Billing_Account_Id__c; + if (!batch.includes(id)) continue; + const opportunity = record.Opportunity__r; + if ( + opportunity != null && + (typeof opportunity !== "object" || + (opportunity.Engagement_Offering_Type__c != null && + typeof opportunity.Engagement_Offering_Type__c !== "string") || + (opportunity.Name != null && typeof opportunity.Name !== "string")) + ) { + throw new BadGatewayException( + "Salesforce returned invalid billing account offerings.", + ); + } + let offering = + opportunity?.Engagement_Offering_Type__c?.trim() || undefined; + // Preserve the same two blank-offering corrections used by customer revenue. + if (!offering && /^topgear$/i.test(opportunity?.Name?.trim() ?? "")) + offering = "TopGear"; + if ( + !offering && + /^multiple app enhancements? 5$/i.test( + opportunity?.Name?.trim() ?? "", + ) + ) { + offering = "Flexible Talent"; + } + const canonical = [ + "AI Training", + "Crowd Powered Outcomes", + "Crowd Powered Innovation", + "Flexible Talent", + "TopGear", + "TaaS Ops", + ].find( + (value) => categoryValue(value) === categoryValue(offering ?? ""), + ); + offering = + categoryValue(offering ?? "") === "topgear ops" + ? "TopGear" + : (canonical ?? offering); + if (offerings.has(id) && offerings.get(id) !== offering) { + throw new BadGatewayException( + "Salesforce returned conflicting billing account offerings.", + ); + } + offerings.set(id, offering); + } + for (const id of batch) { + this.billingOfferings.set(id, { + expires: Date.now() + 60000, + offering: offerings.get(id), + }); + } + } + return new Map( + unique.flatMap((id) => { + const offering = this.billingOfferings.get(id)?.offering; + return offering ? [[id, offering]] : []; + }), + ); + } + /** * Executes a trusted report request with shared validation, retries and OAuth renewal. * @param reportId Configured report ID. @param suffix Internal resource suffix.