@better-giving/donation 3.0.4 → 3.0.6

package/src/interfaces.mts

@@ -0,0 +1,316 @@
+import type { Environment } from "@better-giving/types/list";
+import type { IAllocation, TDonationSource, TDonorTitle } from "./schema.mjs";
+
+interface IReferrerCommission {
+  from_tip: number;
+  from_fee: number;
+  /** exist when paid */
+  transfer_id?: number;
+}
+
+export interface ITributeNotif {
+  toEmail: string;
+  toFullName: string;
+  fromMsg: string;
+}
+
+export type TFiatRamp = "STRIPE" | "CHARIOT" | "PAYPAL";
+export type TOnHoldStatus = "intent" | "pending";
+
+export type TDonationOnholdStatus = "intent" | "pending";
+
+export interface IDonationOnHoldAttrLegacy {
+  /** @deprecated */
+  apesComplianceReviewStatus?: "approved";
+  /** @deprecated */
+  apesComplianceTimeWindow?: string;
+  /** @deprecated */
+  client?: "apes";
+  /** @deprecated */
+  destinationChainId?: "fiat" | "137";
+  /** @deprecated */
+  donationFinalized?: false;
+  /** @deprecated 1-100 str */
+  splitLiq?: string;
+  /** @deprecated - no more inhouse pipeline */
+  third_party?: boolean;
+}
+
+export interface IDonationOnHoldAttr {
+  transactionDate: string;
+  transactionId: string;
+  allocation?: IAllocation;
+  amount: number;
+  status: TOnHoldStatus;
+  tipAmount: number;
+  /**  
+  "USD", "TRX", "karate-295", "BRL", "GBP", "USDC", "JPY", "ETH", "USDCMATIC", "EUR", "INR", "THB", "PHP",
+  "XRP", "RUB", "CAD", "karate-1" ... */
+  denomination: string;
+  /** bg-marketplace | bg-widget */
+  appUsed: TDonationSource;
+  /** "fiat", "trx", "hbar", "eth", "matic", "xrp-mainnet" */
+  chainId: string;
+  /** "Fiat", "TRON", "Hedera", "Ethereum", "", "Polygon", "Stripe", "XRP Ledger" */
+  chainName: string;
+  charityName: string;
+  claimed?: boolean;
+  /** may be empty */
+  company_name?: string;
+  donor_public?: boolean;
+  kycEmail: string;
+  /** @legacy */
+  email?: string;
+  /** 0 when donating to fund */
+  endowmentId: number;
+  fiatRamp?: TFiatRamp;
+  feeAllowance?: number;
+  fiscalSponsored: boolean;
+  fullName: string;
+  /** may be empty, if donation is to npo */
+  fund_id?: string;
+  fund_members?: number[];
+  fund_name?: string;
+  hideBgTip?: boolean;
+  /** may be empty */
+  inHonorOf?: string;
+  isRecurring?: boolean;
+  msg_to_npo?: string;
+  network: Environment;
+  /** may be empty */
+  nonProfitMsg?: string;
+  /** Nowpayments: number, custom: uuid */
+  payment_id?: number | string;
+  /** e.g. Bank transfer */
+  paymentMethod?: string;
+  /** may be empty */
+  programId?: string;
+  /** may be empty */
+  programName?: string;
+  stripeDepositVerifyUrl?: string;
+  /** TTL attribute */
+  expireAt?: number;
+  title?: TDonorTitle;
+  tributeNotif?: ITributeNotif;
+  ukGiftAid?: boolean;
+  usdValue: number;
+  /** may be empty */
+  walletAddress?: string;
+}
+
+export interface IDonationOnHold
+  extends IDonationOnHoldAttr,
+    IDonationOnHoldAttrLegacy {}
+
+export interface IDonationFinalAttrLegacy {
+  /** @deprecated "", " "*/
+  addressComplement?: string;
+  /** @deprecated 4 */
+  apesComplianceNewRecipient?: 4;
+  /** @deprecated "approved", "pending" */
+  apesComplianceReviewStatus?: string;
+  /** @deprecated */
+  apesComplianceTimeWindow?: string;
+  /** @deprecated */
+  charityId?: string | number;
+  /** @deprecated */
+  checked8283?: "no" | "yes";
+  /** @deprecated */
+  client?: "apes" | "normal";
+  /** @deprecated */
+  consent_marketing?: boolean;
+  /** @deprecated */
+  consent_tax?: boolean;
+  /** @deprecated */
+  cryptoFee?: number;
+  /** @deprecated - all donations in this table are settled/final */
+  donationFinalized?: boolean;
+  /** @deprecated */
+  fiscalSponsorshipFee?: number;
+  /** @deprecated */
+  fundDepositTxHash?: string;
+  /** @deprecated */
+  fundId?: number;
+  /** @deprecated */
+  fundMembers?: string[];
+  /** @deprecated may be empty */
+  nftAddress?: string;
+  nftRequested?: boolean;
+  /** @deprecated */
+  receiptRequested?: boolean;
+  /** @deprecated */
+  splitLiq?: string;
+  /** @deprecated "null", "UST", "axlUSDC", "USDC", "nulll"  */
+  swapDenomination?: string;
+  /** @deprecated */
+  swapFinalAmount?: number;
+  /** @deprecated */
+  swapFinished?: boolean;
+  /** @deprecated */
+  swapStarted?: boolean;
+  /** @deprecated */
+  taxReceiptSent?: "yes" | "no";
+  /** @deprecated e.g. "White Whale", "Plutos Pot / Lunaverse", "Spaar"..*/
+  tcaAssociation?: string;
+  /** @deprecated */
+  ustFinal?: number;
+  /** @deprecated */
+  walletAddress?: string;
+}
+
+export type TExplicit<T> = { [K in keyof T]-?: T[K] };
+
+export interface IDonationFinalAttr {
+  amount?: number;
+  allocation?: IAllocation;
+  /** "bg-marketplace", "restore-earth", "angel-protocol",
+  "ukraine-portal", "bg-widget", undefined, "aging", "black-history-month",
+  "make-whole", "mental-health" */
+  appUsed?: TDonationSource | (string & {});
+  baseFee?: number;
+  /**
+  "fiat", "columbus-5", "eth", "matic", "juno-1", "ltc", undefined, "btc", "phoenix-1", "56", "1", "137",
+  "xrp-mainnet", "zec", "sol", "bch", "bsc", "cchain", "xvg", "xrp", "sei-1", "icx", "base",
+  "trx", "avaxc""
+   */
+  chainId?: string;
+  /**
+  "Fiat", "Terra Mainnet", "STRIPE", "Ethereum Mainnet",
+  "Polygon", "Juno Mainnet", "Litecoin", undefined, "Ethereum", "Bitcoin", "Terra Phoenix Mainnet",
+  "Binance Smart Chain", "Polygon Mainnet", "XRP Ledger",
+  "Zcash", "Solana", "BNB Smart Chain Mainnet", "Bitcoin Cash",
+  "Avalanche C-Chain", "Verge", "XRP", "Sei", "ICON", "Base", "TRON", "CHARIOT"
+   */
+  chainName?: string;
+  charityName?: string;
+  /** may be empty */
+  city?: string;
+  claimed?: boolean;
+  /** may be empty */
+  company_name?: string;
+  /** may be empty */
+  country?: string;
+  donor_public?: boolean;
+  donor_message?: string;
+  /**
+  PHP", "UST", "USD", "LUNA", "ETH", "USDCMATIC", "axlUSDC", "LTC", undefined, "EUR", "NZD", "JUNO", "INR",
+  "IDR", "GBP", "USDTMATIC", "PKR", "BTC", "SEK", "HKD", "SGD", "BNB", "CAD", "MATICMAINNET",
+  "USDC", "MOP", "XRP", "JPY", "MATIC", "RSD", "ZEC", "TWD", "SOL", "AUD", "KRW", "BCH", "CHF", "TEL", "USDTBSC",
+  "YER", "ATOM", "AVAXC", "USDTERC20", "XVG", "BUSD", "SEI", "ICX", "ETHBASE", "USDC.e", "USDCBASE", "TRX",
+  "VND", "SZL", "GONE", "AFN", "PLN", "NOK", "WETH", "EGP", "BUSDBSC", "USDCARC20", "USDTTRC20", "THB"
+   */
+  denomination?: string;
+
+  donationFinalAmount?: number;
+  /** 
+  "fiat", undefined, "matic", "137", "noble-1", "eth"*/
+  destinationChainId?: string;
+  /** "fiat", undefined, "matic", "juno-1", "137", "noble-1", "eth" */
+  donationFinalChainId?: string;
+  /**
+   * "USD", "aUSDC", "USDC", "axlUSDC"
+   */
+  donationFinalDenom?: string;
+  /** iso date */
+  donationFinalTxDate?: string;
+  donationFinalTxHash?: string;
+
+  endowmentId?: number;
+  excessFeeAllowanceUsd?: number;
+  feeAllowance?: number;
+
+  fiatRamp?: TFiatRamp;
+  fiscalSponsored?: boolean;
+  fiscalSponsorFee?: number;
+  /** may be empty */
+  fullName?: string;
+  fund_id?: string;
+  fund_name?: string;
+  fund_members?: number[];
+  /** may be empty */
+  inHonorOf?: string;
+  isRecurring?: boolean;
+  kycEmail?: string;
+  /** @warning, about 14 legacy records (~2021) contain invalid email */
+  email?: string;
+  msg_to_npo?: string;
+  network?: Environment;
+  /** may be empty */
+  nonProfitMsg?: string;
+  /** indicates this is a tip record */
+  parentTx?: string;
+  /**
+  "Credit Card", undefined, "Stripe Link", "Bank Transfer",
+  "Crypto", "Debit Card", "link", "Card", "Bank", "crypto", "Amazon Pay", "Daf", "Affirm", "eps", "card",
+  "p24", "affirm"
+   */
+  paymentMethod?: string;
+  processingFee?: number;
+  /** may be empty */
+  programId?: string;
+  /** may be empty */
+  programName?: string;
+  referrer_commission?: IReferrerCommission;
+  referrer?: string;
+  settledUsdAmount?: number;
+  state?: string;
+  /** @legacy may be empty */
+  stateAddress?: string;
+  streetAddress?: string;
+  taxReceiptId?: string;
+  /** Mr Ms Mrs Mx, may be empty */
+  title?: string;
+  /** iso */
+  transactionDate?: string;
+  transactionId: string;
+  tributeNotif?: ITributeNotif;
+  ukGiftAid?: boolean;
+  usdValue?: number;
+  /** may be empty */
+  zipCode?: string;
+}
+
+export interface IDonationFinal
+  extends IDonationFinalAttr,
+    IDonationFinalAttrLegacy {}
+
+export interface IPublicDonor {
+  amount: number;
+  /** iso */
+  date: string;
+  donation_id: string;
+  donor_id: string;
+  donor_message: string;
+  donor_name: string;
+  env: Environment;
+  /** uuidv4 */
+  id: string;
+  /** Endow or fund ID */
+  recipient_id: string;
+}
+
+export interface ISubscription {
+  //PK
+  subscription_id: string;
+  app_used: string;
+  charity_name: string;
+  customer_id: string;
+  email: string;
+  endowment_id: number;
+  fiat_ramp: "STRIPE";
+  fiscal_sponsored: boolean;
+  hide_bg_tip: boolean;
+  /** url*/
+  latest_invoice?: string;
+  network: Environment;
+  product_id: string;
+  /**
+   * Determines overall price the user has to pay
+   * For example, we have a recurring subscription plan of $1 per month.
+   * If quantity is set to 2 then the user pays $2 per month
+   */
+  quantity: number;
+  split_liq: string;
+  /** @link https://docs.stripe.com/billing/subscriptions/overview#payment-status */
+  status: "active" | "incomplete";
+}

package/src/onhold-db.mts

@@ -0,0 +1,118 @@
+import {
+  GetCommand,
+  PutCommand,
+  QueryCommand,
+  UpdateCommand,
+} from "@aws-sdk/lib-dynamodb";
+import { Db, type TxType, UpdateBuilder } from "@better-giving/db";
+import type { IPageKeyed } from "@better-giving/types/api";
+import type {
+  IDonationOnHold,
+  IDonationOnHoldAttr,
+  TExplicit,
+} from "./interfaces.mjs";
+import type { IDonationsSearch } from "./schema.mjs";
+
+type K = keyof IDonationOnHoldAttr;
+
+export class OnHoldDonationsDb extends Db {
+  static readonly table = "on_hold_donations";
+  static readonly gsi_email$tx_date = "email-tx_date-gsi";
+
+  key(id: string) {
+    return { transactionId: id } satisfies Pick<
+      IDonationOnHold,
+      "transactionId"
+    >;
+  }
+
+  async put(data: TExplicit<IDonationOnHoldAttr>) {
+    const cmd = new PutCommand({
+      TableName: OnHoldDonationsDb.table,
+      Item: data,
+      ConditionExpression: `attribute_not_exists(${"transactionId" satisfies keyof IDonationOnHoldAttr})`,
+    });
+    return this.client.send(cmd);
+  }
+
+  async update(
+    id: string,
+    data: Partial<Omit<IDonationOnHoldAttr, "transactionId">>
+  ): Promise<IDonationOnHold> {
+    const upd8 = new UpdateBuilder();
+    for (const k in data) {
+      upd8.set(k as K, (data as any)[k]);
+    }
+    const cmd = new UpdateCommand({
+      TableName: OnHoldDonationsDb.table,
+      Key: this.key(id),
+      ...upd8.collect(),
+    });
+    return this.client.send(cmd).then((r) => r.Attributes as any);
+  }
+
+  async item(id: string): Promise<IDonationOnHold | undefined> {
+    const cmd = new GetCommand({
+      TableName: OnHoldDonationsDb.table,
+      Key: this.key(id),
+    });
+    return this.client.send(cmd).then((r) => r.Item as any);
+  }
+
+  put_txi(data: TExplicit<IDonationOnHoldAttr>) {
+    const cmd = new PutCommand({
+      TableName: OnHoldDonationsDb.table,
+      Item: data,
+      ConditionExpression: `attribute_not_exists(${"transactionId" satisfies keyof IDonationOnHoldAttr})`,
+    });
+    return this.client.send(cmd);
+  }
+  del_txi(id: string): TxType["Delete"] {
+    return { TableName: OnHoldDonationsDb.table, Key: this.key(id) };
+  }
+
+  async list_by_email(
+    email: string,
+    opts?: IDonationsSearch
+  ): Promise<IPageKeyed<IDonationOnHold>> {
+    /** key condition expression */
+    let kce = "#email = :email";
+    /** expression attribute names */
+    const ean: Record<string, string> = {
+      "#email": "email" satisfies K,
+    };
+    /** expression attribute values */
+    const eav: Record<string, any> = {
+      ":email": email,
+    };
+
+    if (opts?.date_start && opts?.date_end) {
+      kce += " AND #settled_date BETWEEN :date_start AND :date_end";
+      ean["#settled_date"] = "transactionDate" satisfies K;
+      eav[":date_start"] = opts.date_start;
+      eav[":date_end"] = opts.date_end;
+    } else if (opts?.date_start) {
+      kce += " AND #settled_date >= :date_start";
+      ean["#settled_date"] = "transactionDate" satisfies K;
+      eav[":date_start"] = opts.date_start;
+    } else if (opts?.date_end) {
+      kce += " AND #settled_date <= :date_end";
+      ean["#settled_date"] = "transactionDate" satisfies K;
+      eav[":date_end"] = opts.date_end;
+    }
+
+    const cmd = new QueryCommand({
+      TableName: OnHoldDonationsDb.table,
+      IndexName: OnHoldDonationsDb.gsi_email$tx_date,
+      KeyConditionExpression: "#email = :email",
+      ExpressionAttributeNames: {
+        "#email": "email" satisfies K,
+      },
+      ExpressionAttributeValues: {
+        ":email": email,
+      },
+      ScanIndexForward: false,
+    });
+    return this.client.send(cmd).then(this.to_page<IDonationOnHold>);
+  }
+}

package/src/paypal.mts

@@ -0,0 +1,85 @@
+export declare namespace FiatDonations {
+  type Currency = {
+    /** lowercase ISO 4217 code */
+    currency_code: string;
+    minimum_amount: number;
+    rate: number;
+    timestamp: string;
+  };
+}
+
+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";
+}

package/src/schema.mts

@@ -1,3 +1,5 @@
+import { $int_gte1 } from "@better-giving/schemas";
+import { endOfDay, iso_date, startOfDay } from "@better-giving/schemas/date";
 import * as v from "valibot";
 export const frequencies = ["one-time", "recurring"] as const;
 export const frequency = v.picklist(
@@ -5,7 +7,7 @@ export const frequency = v.picklist(
   "Please select donation frequency"
 );
 
-export type Frequency = v.InferOutput<typeof frequency>;
+export type TFrequency = v.InferOutput<typeof frequency>;
 
 export const donation_sources = [
   "bg-marketplace",
@@ -14,12 +16,12 @@ export const donation_sources = [
 ] as const;
 
 export const donation_source = v.picklist(donation_sources);
-export type DonationSource = v.InferOutput<typeof donation_source>;
+export type TDonationSource = v.InferOutput<typeof donation_source>;
 
 export const donor_titles = ["Mr", "Mrs", "Ms", "Mx", ""] as const;
 export const donor_title = v.picklist(donor_titles);
 
-export type DonorTitle = v.InferOutput<typeof donor_title>;
+export type TDonorTitle = v.InferOutput<typeof donor_title>;
 
 const pct = v.pipe(v.number(), v.minValue(0), v.maxValue(100));
 export const allocation = v.pipe(
@@ -31,4 +33,34 @@ export const allocation = v.pipe(
   v.check((x) => x.liq + x.lock + x.cash === 100, "Allocation must sum to 100%")
 );
 
-export type Allocation = v.InferOutput<typeof allocation>;
+export type IAllocation = v.InferOutput<typeof allocation>;
+
+export const page_opts = v.object({
+  limit: v.optional($int_gte1),
+  next: v.optional(v.pipe(v.string(), v.base64())),
+});
+
+export interface IPageOpts extends v.InferOutput<typeof page_opts> {}
+
+const donations_search_raw = v.object({
+  ...page_opts.entries,
+  date_start: v.optional(iso_date(startOfDay)),
+  date_end: v.optional(iso_date(endOfDay)),
+});
+
+export const donations_search = v.pipe(
+  donations_search_raw,
+  v.forward(
+    v.partialCheck(
+      [["date_start"], ["date_end"]],
+      ({ date_start: a, date_end: b }) => {
+        return a && b ? a <= b : true;
+      },
+      "start date must be earlier than end date"
+    ),
+    ["date_start"]
+  )
+);
+
+export interface IDonationsSearch
+  extends v.InferOutput<typeof donations_search_raw> {}

package/src/subscriptions-db.mts

@@ -0,0 +1,50 @@
+import {
+  DeleteCommand,
+  PutCommand,
+  UpdateCommand,
+} from "@aws-sdk/lib-dynamodb";
+import { Db, UpdateBuilder } from "@better-giving/db";
+import type { ISubscription } from "./interfaces.mjs";
+
+type K = keyof ISubscription;
+export class SubsDb extends Db {
+  static readonly table = "subscriptions";
+
+  key(id: string) {
+    return { subscription_id: id } satisfies Pick<
+      ISubscription,
+      "subscription_id"
+    >;
+  }
+  async put(data: ISubscription) {
+    const cmd = new PutCommand({
+      TableName: SubsDb.table,
+      Item: data,
+      ConditionExpression: `attribute_not_exists(${"subscription_id" satisfies K})`,
+    });
+    return this.client.send(cmd);
+  }
+  async update(
+    id: string,
+    data: Partial<Omit<ISubscription, "subscription_id">>
+  ): Promise<ISubscription> {
+    const upd8 = new UpdateBuilder();
+    for (const k in data) {
+      upd8.set(k as K, (data as any)[k]);
+    }
+    const cmd = new UpdateCommand({
+      TableName: SubsDb.table,
+      Key: this.key(id),
+      ...upd8.collect(),
+    });
+    return this.client.send(cmd).then((r) => r.Attributes as any);
+  }
+
+  async del(id: string) {
+    const cmd = new DeleteCommand({
+      TableName: SubsDb.table,
+      Key: this.key(id),
+    });
+    return this.client.send(cmd);
+  }
+}

package/src/donation-message.mts

@@ -1,39 +0,0 @@
-import type { ISODate } from "@better-giving/types/alias";
-import type { Environment } from "@better-giving/types/list";
-
-export type DMKey = `DM#${string}`;
-
-export declare namespace GSI1 {
-  type Name = "recipient-env-gsi";
-
-  interface Key {
-    /** `Recipient#{recipient_id}#{env}` */
-    gsi1PK: `Recipient#${string}#${Environment}`;
-    gsi1SK: ISODate;
-  }
-}
-
-export declare namespace DonationMessage {
-  /** `DM#{uuid}` */
-  interface PrimaryKey {
-    PK: DMKey;
-    SK: DMKey;
-  }
-
-  interface NonKeyAttributes {
-    /** USD amount at the time of donation */
-    amount: number;
-    date: ISODate;
-    donation_id: string;
-    donor_id: string;
-    donor_message: string;
-    donor_name: string;
-    env: Environment;
-    /** uuidv4 */
-    id: string;
-    /** Endow or fund ID */
-    recipient_id: string;
-  }
-
-  interface DBRecord extends PrimaryKey, NonKeyAttributes, GSI1.Key {}
-}