@better-giving/donation 1.0.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@better-giving/donation",
+  "version": "1.0.0",
+  "devDependencies": {
+    "@better-giving/config": "workspace:*"
+  },
+  "peerDependencies": {
+    "@better-giving/types": "1.0.1",
+    "valibot": "0.42.0"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/donation.mjs",
+    "./*": "./dist/*.mjs"
+  },
+  "scripts": {
+    "build": "tsc --outDir dist",
+    "publish": "npm publish --access public"
+  }
+}

package/src/donation.mts

@@ -0,0 +1,535 @@
+import type { ISODate } from "@better-giving/types/alias";
+import type { ChainID, Environment } from "@better-giving/types/list";
+import type { EmptyObject, OrStr } from "@better-giving/types/utils";
+
+export declare namespace Donation {
+  type Index =
+    | "AppUsed_Index"
+    | "Checked-8283_Index"
+    | "Email_Index"
+    | "EndowmentId_Index"
+    | "FundDeposits_Index"
+    | "Tax-Receipt-Sent_Index"
+    | "Network-FinalizedDate_Index"
+    | "WalletAddress_Index";
+
+  type App =
+    | "aging"
+    | "angel-protocol"
+    | "bg-marketplace"
+    | "bg-widget"
+    | "black-history-month"
+    | "make-whole"
+    | "mental-health"
+    | "restore-earth"
+    | "tester-app"
+    | "ukraine-portal";
+
+  type Source = Extract<
+    Donation.App,
+    "bg-marketplace" | "bg-widget" | "tester-app"
+  >;
+
+  type Client = "apes" | "normal";
+
+  type ApesComplianceReviewStatus = "pending" | "approved";
+
+  type PrimaryKey = {
+    transactionId: string; //PK
+  };
+  /** AppUsed_Index */
+  type AppUsed_IndexKey = {
+    appUsed?: App; //PK
+  };
+
+  /** Checked-8283_Index */
+  type Checked_8283_IndexKey = {
+    checked8283?: "yes" | "no"; //PK
+  };
+
+  /** Email_Index */
+  type EmailIndexKey = {
+    /** donor email */
+    email?: string; //PK
+  };
+
+  /** EndowmentId_Index */
+  type EndowmentId_IndexKey = {
+    endowmentId?: number; //PK
+  };
+
+  type FiatRamp_IndexKey = {
+    fiatRamp?: "STRIPE" | "PAYPAL" | "CHARIOT";
+  };
+
+  /** FundDeposits_Index */
+  type FundDeposits_IndexKey = {
+    fundDepositTxHash?: string; //PK
+    donationFinalTxHash?: string; //SK
+  };
+
+  /** Network-FinalizedDate_Index */
+  type Network_FinalizedDate_IndexKey = {
+    network: Environment; //PK
+    donationFinalTxDate: ISODate; //SK
+  };
+
+  /** Tax-Receipt-Sent_Index */
+  type Tax_Receipt_Sent_IndexKey = {
+    taxReceiptSent?: "yes" | "no"; //PK
+  };
+
+  /** WalletAddress_Index */
+  type WalletAddress_Index = {
+    walletAddress?: string; //PK
+  };
+
+  type DonorTitle = "Mr" | "Ms" | "Mrs" | "Mx";
+  type DonorBasicInfo = {
+    /** may be empty */
+    title?: DonorTitle;
+    fullName: string;
+    kycEmail: string;
+    /** signifies eligibility to UK Gift Aid, defaults to `false` for crypto donations */
+    ukGiftAid: boolean;
+  };
+  type DonorAddress = {
+    streetAddress: string;
+    /** may be empty `''` */
+    city: string;
+    /** optional */
+    state?: string;
+    zipCode: string;
+    country: string;
+  };
+
+  type V2FullKyc = DonorBasicInfo & DonorAddress;
+  type V2Kyc = DonorBasicInfo | V2FullKyc;
+  type PartialV2Kyc = Partial<V2FullKyc>;
+
+  type V2NonKeyAttributes = {
+    /** program which the donation is attributed: may be empty `""` */
+    programId?: string;
+    programName?: string;
+    /** honorary full name - may be empty `""` */
+    inHonorOf?: string;
+    transactionDate: ISODate;
+    /** if tipAmount is present, value includes tipAmount */
+    amount: number;
+    /** USD value at the time of donation */
+    usdValue: number;
+    /**
+     * settled USD amount before fsa,base fees
+     *
+     * Crypto: post-swaps USDC amount and converted to USD equivalent
+     *
+     * Fiat: 1:1 for USD donations while post-FX conversion for non USD donations
+     */
+    settledUsdAmount: number;
+    feeAllowance: number;
+    /** what's left of feeAllowance after covering processing fee, could be less than 0 (loss) */
+    excessFeeAllowanceUsd: number;
+    /** indicates DB record is not yet separated into endow-record & tip-record */
+    tipAmount?: number;
+    /** indicates this is a tip record extracted from parent */
+    parentTx?: string;
+
+    denomination: string;
+    chainId: ChainID.V2SupportedChainID;
+    chainName: string;
+    /** 0 - 100 */
+    splitLiq: string;
+
+    charityName: string;
+    nonProfitMsg?: string;
+    fiscalSponsored: boolean;
+    client: Client;
+    network: Environment;
+    paymentMethod: string;
+    isRecurring: boolean;
+
+    //finalized
+    destinationChainId: OrStr<ChainID.V2DestinationChainID>;
+    donationFinalAmount: number;
+    donationFinalChainId: OrStr<ChainID.V2DestinationChainID>;
+    donationFinalDenom: string;
+    donationFinalTxDate: ISODate;
+    donationFinalTxHash: string;
+
+    //fees
+    baseFee: number;
+    processingFee: number;
+    fiscalSponsorFee: number;
+
+    /// fundraiser this donation is attributed to
+    fund_id?: string;
+    fund_name?: string;
+    fund_tx?: string;
+  };
+
+  type NonKeyAttributes = {
+    addressComplement?: " ";
+    /** one record with this value */
+    apesComplianceNewRecipient?: 4;
+    apesComplianceReviewStatus?: ApesComplianceReviewStatus;
+    apesComplianceTimeWindow?: ISODate;
+    /** source chainID */
+    chainId?:
+      | ChainID.V2SupportedChainID
+      /** terra */
+      | "bombay-12"
+      | "columbus-5"
+      //juno
+      | "uni-4"
+      | "uni-5";
+
+    /** string charityId is terra endow address */
+    charityId?: string | number;
+
+    consent_marketing?: boolean;
+    consent_tax?: boolean;
+    cryptoFee?: number;
+    donationFinalChainId?:
+      | ChainID.V2DestinationChainID
+      | "juno-1"
+      | "staging"
+      | "uni-4"
+      | "uni-5";
+
+    fiscalSponsorshipFee?: number;
+    /** @deprecated */
+    fundId?: number;
+    /** @deprecated only one record with this value */
+    fundMembers?: string[];
+    name?: string;
+    nftAddress?: string;
+    nftRequested?: boolean;
+    receiptRequested?: boolean;
+
+    stateAddress?: string;
+    /** initialized as "null" */
+    swapDenomination?: string;
+    swapFinalAmount?: number;
+    swapFinished?: boolean;
+    swapStarted?: boolean;
+    taxReceiptId?: string;
+    tcaAssociation?: string;
+    transactionDate: ISODate;
+    ustFinal?: number;
+  } & PartialV2Kyc &
+    // omitted attributes, to not override broader definition
+    Partial<
+      Omit<
+        V2NonKeyAttributes,
+        "chainId" | "donationFinalChainId" | "transactionDate"
+      >
+    >;
+
+  type DBRecord = PrimaryKey &
+    AppUsed_IndexKey &
+    Checked_8283_IndexKey &
+    EmailIndexKey &
+    EndowmentId_IndexKey &
+    FiatRamp_IndexKey &
+    FundDeposits_IndexKey &
+    Network_FinalizedDate_IndexKey &
+    Tax_Receipt_Sent_IndexKey &
+    WalletAddress_Index &
+    NonKeyAttributes;
+
+  type WithoutKYC = { kycEmail?: never };
+  type WithKYC = V2Kyc;
+
+  /** only use this definition on writes: for reads, it's safer to use DBRecord */
+  type V2DBRecord = PrimaryKey &
+    EmailIndexKey &
+    FiatRamp_IndexKey &
+    /** be sure to include in crypto donation */
+    WalletAddress_Index &
+    Required<EndowmentId_IndexKey> &
+    Required<AppUsed_IndexKey> &
+    (WithKYC | WithoutKYC) &
+    V2NonKeyAttributes;
+
+  /** only use this definition on writes: for reads, it's safer to use DBRecord */
+  type V2InitCryptoDBRecord = PrimaryKey &
+    EmailIndexKey &
+    /** be sure to include in crypto donation */
+    WalletAddress_Index &
+    Required<EndowmentId_IndexKey> &
+    Required<AppUsed_IndexKey> &
+    (WithKYC | WithoutKYC);
+
+  type TributeNotif = {
+    toFullName: string;
+    toEmail: string;
+    /** may be empty `""` */
+    fromMsg: string;
+  };
+
+  export namespace Intent {
+    interface Donor {
+      /** may be empty `''` */
+      title?: DonorTitle;
+      firstName: string;
+      lastName: string;
+      email: string;
+      address?: DonorAddress;
+      /** signifies eligibility to UK Gift Aid, defaults to `false` for crypto donations */
+      ukGiftAid: boolean;
+    }
+
+    interface Attr {
+      transactionId?: string;
+      amount: number;
+      tipAmount: number;
+      feeAllowance: number;
+      endowmentId: number;
+      /** program donation: may be empty `""`*/
+      programId?: string;
+      programName?: string;
+      splitLiq: number;
+      donor: Donor;
+      /** honorary full name */
+      inHonorOf?: string;
+      /** only allowed if honoree is provided */
+      tributeNotif?: TributeNotif;
+      source: Source;
+    }
+
+    interface Crypto extends Attr {
+      denomination: string;
+      chainId: ChainID.V2CryptoChainID;
+      walletAddress?: string;
+      chainName: string;
+    }
+
+    interface Fiat extends Attr {
+      currency: string;
+    }
+  }
+
+  /** web-app determinant: show signup page or not*/
+  type GuestDonor = {
+    email: string;
+    fullName: string;
+  };
+}
+
+export declare namespace OnHoldDonation {
+  type PrimaryKey = {
+    transactionId: string; //PK
+  };
+
+  type Index = "Email_Index" | "EndowmentId_Index" | "fiatRamp_Index";
+
+  type ApesAttributes = {
+    client: Extract<Donation.Client, "apes">;
+    apesComplianceReviewStatus: Donation.ApesComplianceReviewStatus;
+    apesComplianceTimeWindow: ISODate;
+  };
+
+  type CryptoAttributes = {
+    chainId: ChainID.V2CryptoChainID;
+    destinationChainId: Exclude<ChainID.V2DestinationChainID, "fiat">;
+    walletAddress: string;
+    /** status of this record should NOT be changed by our pipelines */
+    third_party?: true;
+    payment_id?: number;
+  };
+
+  type FiatAttributes = {
+    chainId: ChainID.V2FiatChainID;
+    destinationChainId: Extract<ChainID.V2DestinationChainID, "fiat">;
+    /** we can only know the method once it's confirmed by webhook */
+    paymentMethod?: string;
+    /** only exists if donor opts for manual bank verification */
+    stripeDepositVerifyUrl?: string;
+    // TODO: create donation intents for subscriptions as well, then uncomment the below line
+    // frequency: FiatDonations.Frequency;
+  };
+
+  type NonKeyAttributes = {
+    /** tip, fee-allowance is included*/
+    amount: number;
+    /** tip, fee-allowance is included*/
+    usdValue: number;
+    /** same denomination as amount */
+    tipAmount?: number;
+    /** same denomination as amount */
+    feeAllowance?: number;
+    appUsed: Donation.App;
+    chainName: string;
+    /** fund name or npo name, as onhold records not yet distributed */
+    charityName: string;
+    nonProfitMsg?: string;
+    /** upper case */
+    denomination: string;
+    donationFinalized: boolean;
+    endowmentId: number;
+    /** donation to fund */
+    fund_id?: string;
+    /** donation to fund */
+    fund_name?: string;
+    /** endowment ids */
+    fund_members?: number[];
+    /** program donation: may be empty `""`*/
+    programId?: string;
+    programName?: string;
+    fiscalSponsored: boolean;
+    hideBgTip?: boolean;
+    network: Environment;
+    /** "0" - "100" */
+    splitLiq: string;
+    status?: "intent" | "pending";
+    transactionDate: ISODate;
+    /** TTL attribute */
+    expireAt?: number;
+    /** for new records only: `true` is recurring */
+    isRecurring?: boolean;
+    /** honorary full name - may be empty `''` */
+    inHonorOf?: string;
+    /** only allowed if honoree is provided */
+    tributeNotif?: Donation.TributeNotif;
+  } & (ApesAttributes | EmptyObject) &
+    (Donation.WithKYC | Donation.WithoutKYC);
+
+  type CryptoDBRecord = PrimaryKey &
+    NonKeyAttributes &
+    CryptoAttributes &
+    Donation.EmailIndexKey;
+
+  type FiatDBRecord = PrimaryKey &
+    Required<Donation.FiatRamp_IndexKey> &
+    NonKeyAttributes &
+    FiatAttributes &
+    Required<Donation.EmailIndexKey>; //email is required for fiat donations
+
+  type DBRecord = CryptoDBRecord | FiatDBRecord;
+
+  /** Only used when donation is finalized and ready for transfer to Donations DB */
+}
+
+export declare namespace FiatDonations {
+  type Currency = {
+    /** lowercase ISO 4217 code */
+    currency_code: string;
+    minimum_amount: number;
+    rate: number;
+    timestamp: string;
+  };
+
+  type Frequency = "one-time" | "subscription";
+}
+
+export declare namespace PayPalDonation {
+  type CreateOrder = {
+    purchase_units: PurchaseUnit[];
+    intent: Intent;
+    payment_source?: PaymentSource;
+  };
+
+  // see Response object description in official docs
+  // https://developer.paypal.com/docs/api/orders/v2/#orders_create
+  type Order = {
+    id: string;
+    status: Status;
+    intent: Intent;
+    payment_source: PaymentSource;
+    purchase_units: PurchaseUnit[];
+    payer: Payer;
+    create_time: Date;
+    links: Link[];
+  };
+
+  type Link = {
+    href: string;
+    rel: string;
+    method: string;
+  };
+
+  type Payer = {
+    name: Name;
+    email_address: string;
+    payer_id: string;
+  };
+
+  type PaymentSource = {
+    paypal: {
+      name: Name;
+      email_address: string;
+      account_id: string;
+    };
+  };
+
+  type Name = {
+    given_name: string;
+    surname: string;
+  };
+
+  type PurchaseUnit = {
+    // don't need 'reference_id'
+    amount: {
+      /** Three-character ISO-4217 code. */
+      currency_code: string;
+      value: string;
+    };
+    /** @link https://developer.paypal.com/docs/api/orders/v2/#orders_get */
+    payments?: {
+      captures: CapturedPayment[];
+    };
+  };
+
+  type CapturedPayment = {
+    seller_receivable_breakdown: {
+      gross_amount: { value: number };
+      paypal_fee: { value: number };
+      net_amount: { value: number };
+    };
+  };
+
+  type Intent = "CAPTURE" | "AUTHORIZE";
+  type Status =
+    | "CREATED"
+    | "SAVED"
+    | "APPROVED"
+    | "VOIDED"
+    | "COMPLETED"
+    | "PAYER_ACTION_REQUIRED";
+}
+
+export declare namespace StripeDonation {
+  /** DEPRECATED - can be removed eventually as existing records will eventually "expire" */
+  type LegacyMetadata = {
+    /** This attr will help in identifying PaymentIntents made for one-time donations only */
+    donation_type: Extract<FiatDonations.Frequency, "one-time">;
+    /** This attr will link the received webhook event to a donation intent */
+    intent_tx_id: string;
+  };
+
+  /**
+   * Stripe forces metadata to be typeof `string`
+   * @link https://docs.stripe.com/metadata/use-cases#store-structured-data
+   */
+  type Metadata = {
+    [K in keyof OnHoldDonation.FiatDBRecord]: string;
+  } & {
+    // KYC fields
+    title?: Donation.DonorTitle;
+    fullName: string;
+    ukGiftAid: string;
+    streetAddress?: string;
+    /** may be empty `''` */
+    city?: string;
+    /** optional */
+    state?: string;
+    zipCode?: string;
+    country?: string;
+  };
+
+  type SetupIntentMetadata = Metadata & {
+    // Subs specific fields
+    productId: string;
+    subsQuantity: string;
+  };
+}

package/src/final-recorder.mts

@@ -0,0 +1,48 @@
+import type { Donation } from "./donation.mjs";
+
+type FinalRecord = Pick<
+  Donation.V2DBRecord,
+  | "amount"
+  | "appUsed"
+  | "chainName"
+  | "charityName"
+  | "denomination"
+  | "email"
+  | "endowmentId"
+  | "feeAllowance"
+  | "fiatRamp"
+  | "fiscalSponsored"
+  | "inHonorOf"
+  | "isRecurring"
+  | "network"
+  | "nonProfitMsg"
+  | "paymentMethod"
+  | "programId"
+  | "programName"
+  | "splitLiq"
+  | "tipAmount"
+  | "transactionDate"
+  | "transactionId"
+  | "usdValue"
+>;
+
+interface SettledAmounts {
+  settledFee: number;
+  settledNet: number;
+}
+
+/** donation is to fund */
+interface Fund {
+  fund_id?: string;
+  fund_name?: string;
+  fund_members?: number[];
+}
+
+export type FinalRecorderPayload = {
+  /** intent to delete */
+  intentId?: string;
+  hideBgTip: boolean;
+} & FinalRecord &
+  SettledAmounts &
+  Fund &
+  (Donation.WithKYC | Donation.WithoutKYC);

package/src/get-min-fee-allowance.mts

@@ -0,0 +1,20 @@
+/**
+ * @param amount endow amount + tip
+ * @param rate 0-1, to be applied to amount @example `amount * rate`
+ * @param flat flat amount added to `amount * rate`. NOTE: make sure that this is in the same unit as `amount`
+ * @returns number
+ */
+export const getMinFeeAllowance = (
+  amount: number,
+  rate: number,
+  flat = 0
+): number => {
+  /**
+   * fee(1) = amount * rate + flat
+   * fee(2) = (amount + fee(1)) * rate + flat
+   * fee(3) = (amount + fee(2)) * rate + flat
+   * i.e. F₍ₙ₎ = a · ∑ᵏ⁼¹ⁿ (rᵏ) + f · ∑ᵏ⁼⁰ⁿ⁻¹ (rᵏ)
+   * which converges to this formula: n approaches infinity
+   */
+  return (amount * rate + flat) / (1 - rate);
+};