ContributionFlow: Information requirement resolvers

migrations/20250123143500-index-transactions-fromCollective-hostCollective.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/** @type {import('sequelize-cli').Migration} */
+module.exports = {
+  async up(queryInterface) {
+    await queryInterface.sequelize.query(`
+      CREATE INDEX CONCURRENTLY transactions__contributions_fromcollective_to_host
+        ON "Transactions" ("HostCollectiveId", "FromCollectiveId", "createdAt")
+        WHERE ("deletedAt" IS NULL AND "kind" = 'CONTRIBUTION' AND "RefundTransactionId" IS NULL);
+    `);
+  },
+
+  async down(queryInterface) {
+    await queryInterface.sequelize.query(`
+      DROP INDEX CONCURRENTLY transactions__contributions_fromcollective_to_host;
+    `);
+  },
+};

server/constants/policies.ts

@@ -20,6 +20,8 @@ enum POLICIES {
   // When enabled, admins of the collective are allowed to see the payout methods of expenses
   COLLECTIVE_ADMINS_CAN_SEE_PAYOUT_METHODS = 'COLLECTIVE_ADMINS_CAN_SEE_PAYOUT_METHODS',
   EXPENSE_POLICIES = 'EXPENSE_POLICIES',
+  /** Enforces contributor information requirements based on yearly contribution amount thresholds */
+  CONTRIBUTOR_INFO_THRESHOLDS = 'CONTRIBUTOR_INFO_THRESHOLDS',
 }
 
 export type Policies = Partial<{
@@ -51,6 +53,10 @@ export type Policies = Partial<{
   };
   [POLICIES.EXPENSE_PUBLIC_VENDORS]: boolean;
   [POLICIES.COLLECTIVE_ADMINS_CAN_SEE_PAYOUT_METHODS]: boolean;
+  [POLICIES.CONTRIBUTOR_INFO_THRESHOLDS]: {
+    legalName?: number;
+    address?: number;
+  };
 }>;
 
 export const DEFAULT_POLICIES: { [T in POLICIES]: Policies[T] } = {
@@ -88,6 +94,7 @@ export const DEFAULT_POLICIES: { [T in POLICIES]: Policies[T] } = {
   },
   [POLICIES.EXPENSE_PUBLIC_VENDORS]: false,
   [POLICIES.COLLECTIVE_ADMINS_CAN_SEE_PAYOUT_METHODS]: false,
+  [POLICIES.CONTRIBUTOR_INFO_THRESHOLDS]: undefined,
 };
 
 export default POLICIES;

server/graphql/loaders/contributors.ts

@@ -1,10 +1,13 @@
 import DataLoader from 'dataloader';
-import { uniq, zipObject } from 'lodash';
+import { compact, uniq, zipObject } from 'lodash';
 
+import { SupportedCurrency } from '../../constants/currencies';
 import { ContributorsCacheEntry, getContributorsForCollective } from '../../lib/contributors';
-import models from '../../models';
+import models, { sequelize } from '../../models';
 
-export default {
+import { sortResultsSimple } from './helpers';
+
+const loaders = {
   forCollectiveId: (): DataLoader<number, ContributorsCacheEntry> =>
     new DataLoader(async collectiveIds => {
       const uniqueIds = uniq(collectiveIds);
@@ -17,4 +20,53 @@ export default {
       const result = collectiveIds.map(id => contributorsByIds[id]);
       return result;
     }),
+
+  totalContributedToHost: {
+    buildLoader: ({
+      since,
+      hostId,
+    }: {
+      hostId: number;
+      since: Date | string;
+    }): DataLoader<
+      number,
+      { CollectiveId: number; amount: number; currency: SupportedCurrency; HostCollectiveId: number }
+    > => {
+      const key = compact([hostId, since]).join('-');
+      if (!loaders.totalContributedToHost[key]) {
+        loaders.totalContributedToHost[key] = new DataLoader(async (collectiveIds: number[]) => {
+          const stats = await sequelize.query(
+            `
+            SELECT t."FromCollectiveId" as "CollectiveId", SUM (t."amountInHostCurrency") as amount, t."hostCurrency" as currency, t."HostCollectiveId"
+            FROM "Transactions" t
+            WHERE t."FromCollectiveId" IN (:collectiveIds)
+              AND t.kind = 'CONTRIBUTION'
+              AND t."HostCollectiveId" = :hostId
+              AND t."deletedAt" IS NULL
+              AND t."RefundTransactionId" IS NULL
+              AND t."createdAt" >= :since
+            GROUP BY t."FromCollectiveId", t."HostCollectiveId", t."hostCurrency"
+            `,
+            {
+              replacements: {
+                collectiveIds,
+                since,
+                hostId,
+              },
+              type: sequelize.QueryTypes.SELECT,
+              raw: true,
+            },
+          );
+
+          return sortResultsSimple(collectiveIds, stats, row => row.CollectiveId);
+        });
+      }
+
+      return loaders.totalContributedToHost[key];
+    },
+  },
 };
+
+export type ContributorsLoaders = typeof loaders;
+
+export default loaders;

server/graphql/loaders/index.js

@@ -74,6 +74,7 @@ export const loaders = req => {
   // Contributors
   context.loaders.Contributors = {
     forCollectiveId: contributorsLoaders.forCollectiveId(),
+    totalContributedToHost: contributorsLoaders.totalContributedToHost,
   };
 
   // Expense

server/graphql/v2/input/PoliciesInput.ts

@@ -58,5 +58,14 @@ export const GraphQLPoliciesInput = new GraphQLInputObjectType({
     [POLICIES.COLLECTIVE_ADMINS_CAN_SEE_PAYOUT_METHODS]: {
       type: GraphQLBoolean,
     },
+    [POLICIES.CONTRIBUTOR_INFO_THRESHOLDS]: {
+      type: new GraphQLInputObjectType({
+        name: 'PoliciesContributorInfoThresholdsInput',
+        fields: () => ({
+          legalName: { type: GraphQLInt },
+          address: { type: GraphQLInt },
+        }),
+      }),
+    },
   }),
 });

server/graphql/v2/object/ContributorProfile.ts

@@ -1,7 +1,12 @@
-import { GraphQLObjectType } from 'graphql';
+import { GraphQLBoolean, GraphQLObjectType } from 'graphql';
+import { GraphQLDateTime } from 'graphql-scalars';
+import moment from 'moment';
 
+import type { ContributorsLoaders } from '../../loaders/contributors';
 import { GraphQLAccount } from '../interface/Account';
 
+import { GraphQLAmount } from './Amount';
+
 export const GraphQLContributorProfile = new GraphQLObjectType({
   name: 'ContributorProfile',
   description: 'This represents a profile that can be use to create a contribution',
@@ -10,5 +15,45 @@ export const GraphQLContributorProfile = new GraphQLObjectType({
       type: GraphQLAccount,
       description: 'The account that will be used to create the contribution',
     },
+    forAccount: {
+      type: GraphQLAccount,
+      description: 'The account that will receive the contribution',
+    },
+    totalContributedToHost: {
+      type: GraphQLAmount,
+      description: 'The total amount contributed to the host by this contributor',
+      args: {
+        inCollectiveCurrency: {
+          type: GraphQLBoolean,
+          defaultValue: false,
+          description: 'When true, the amount is converted to the currency of the collective',
+        },
+        since: {
+          type: GraphQLDateTime,
+          description: 'The date since when to calculate the total. Defaults to the start of the current year.',
+        },
+      },
+      resolve: async ({ account, forAccount }, args, req) => {
+        const host = await req.loaders.Collective.byId.load(forAccount.HostCollectiveId);
+        const since = args.since ? moment(args.since).toISOString() : moment.utc().startOf('year').toISOString();
+        const stats = await (req.loaders.Contributors as ContributorsLoaders).totalContributedToHost
+          .buildLoader({ hostId: host.id, since })
+          .load(account.id);
+
+        const currency = args.inCollectiveCurrency ? forAccount.currency : host.currency;
+        if (!stats) {
+          return { value: 0, currency };
+        }
+
+        if (args.inCollectiveCurrency && stats.currency !== currency) {
+          const convertParams = { amount: stats.amount, fromCurrency: stats.currency, toCurrency: currency };
+          return {
+            value: await req.loaders.CurrencyExchangeRate.convert.load(convertParams),
+            currency,
+          };
+        }
+        return { value: stats.amount, currency };
+      },
+    },
   }),
 });

server/graphql/v2/object/Individual.ts

@@ -5,7 +5,7 @@ import { uniqBy } from 'lodash';
 import { roles } from '../../../constants';
 import { CollectiveType } from '../../../constants/collectives';
 import twoFactorAuthLib from '../../../lib/two-factor-authentication';
-import models, { Op } from '../../../models';
+import models, { Collective, Op } from '../../../models';
 import UserTwoFactorMethod from '../../../models/UserTwoFactorMethod';
 import { getContextPermission, PERMISSION_TYPE } from '../../common/context-permissions';
 import { checkScope } from '../../common/scope-check';
@@ -238,7 +238,7 @@ export const GraphQLIndividual = new GraphQLObjectType({
             type: new GraphQLNonNull(GraphQLAccountReferenceInput),
           },
         },
-        async resolve(userCollective, args, req: Request) {
+        async resolve(userCollective: Collective, args, req: Request) {
           const loggedInUser = req.remoteUser;
           const forAccount = await fetchAccountWithReference(args.forAccount, {
             throwIfMissing: true,
@@ -283,11 +283,11 @@ export const GraphQLIndividual = new GraphQLObjectType({
             ],
           });
 
-          const contributorProfiles = [{ account: userCollective }];
+          const contributorProfiles = [{ account: userCollective, forAccount }];
           memberships.forEach(membership => {
-            contributorProfiles.push({ account: membership.collective });
+            contributorProfiles.push({ account: membership.collective, forAccount });
             membership.collective.children?.forEach(children => {
-              contributorProfiles.push({ account: children });
+              contributorProfiles.push({ account: children, forAccount });
             });
           });
           return uniqBy(contributorProfiles, 'account.id');

server/graphql/v2/object/Policies.ts

@@ -1,15 +1,21 @@
 import { GraphQLBoolean, GraphQLInt, GraphQLObjectType, GraphQLString } from 'graphql';
-import { get } from 'lodash';
+import { get, isEmpty, isNil, mapValues } from 'lodash';
 
-import POLICIES from '../../../constants/policies';
+import POLICIES, { Policies } from '../../../constants/policies';
 import { VirtualCardLimitIntervals } from '../../../constants/virtual-cards';
+import { getFxRate } from '../../../lib/currency';
 import { getPolicy } from '../../../lib/policies';
 import { checkScope } from '../../common/scope-check';
 import { GraphQLPolicyApplication } from '../enum/PolicyApplication';
 import { getIdEncodeResolver, IDENTIFIER_TYPES } from '../identifiers';
 
 import { GraphQLAmount } from './Amount';
 
+const DEFAULT_USD_THRESHOLDS: Policies[POLICIES.CONTRIBUTOR_INFO_THRESHOLDS] = {
+  address: 5000e2,
+  legalName: 250e2,
+};
+
 export const GraphQLPolicies = new GraphQLObjectType({
   name: 'Policies',
   fields: () => ({
@@ -133,5 +139,31 @@ export const GraphQLPolicies = new GraphQLObjectType({
         }
       },
     },
+    [POLICIES.CONTRIBUTOR_INFO_THRESHOLDS]: {
+      type: new GraphQLObjectType({
+        name: POLICIES.CONTRIBUTOR_INFO_THRESHOLDS,
+        fields: () => ({
+          legalName: { type: GraphQLInt },
+          address: { type: GraphQLInt },
+        }),
+      }),
+      description:
+        'Contribution threshold to enforce contributor info. This resolver can be called from the collective or the host, when resolved through the collective the thresholds are returned in the collective currency',
+      async resolve(account, args, req) {
+        const host =
+          account.HostCollectiveId && account.HostCollectiveId !== account.id
+            ? await req.loaders.Collective.byId.load(account.HostCollectiveId)
+            : account;
+        let thresholds = await getPolicy(host, POLICIES.CONTRIBUTOR_INFO_THRESHOLDS, req);
+        let fxRate = 1;
+        if (!thresholds || isEmpty(thresholds)) {
+          fxRate = await getFxRate('USD', account.currency);
+          thresholds = DEFAULT_USD_THRESHOLDS;
+        } else if (host.currency !== account.currency) {
+          fxRate = await getFxRate(host.currency, account.currency);
+        }
+        return mapValues(thresholds, threshold => (isNil(threshold) ? null : Math.round(threshold * fxRate)));
+      },
+    },
   }),
 });