better-supabase 0.13.0 → 0.14.0

package/dist/blocks/donations/index.d.ts

@@ -0,0 +1,352 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, t as AsyncResult } from "../../result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "../../standard-DbQsD2xZ.js";
+import { n as ExtraFields, r as FieldsOf } from "../../block-fields-3w4MZr8U.js";
+import { dt as SubjectRef } from "../../executor-CPyrQdjh.js";
+import { Ct as Events } from "../../events-DbLjvxDX.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { n as BlockOptions } from "../../block-helpers-BaugZlJV.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-d53POsem.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-CmjPKqQ_.js";
+import { Lt as Section, c as BlockOf, rn as EntitySchema } from "../../define-block-COpcS6aT.js";
+import { n as Money } from "../../money-BNRdJQzA.js";
+import { r as WebhookInput } from "../../signatures-zbu6KTNQ.js";
+import { i as PaymentEvent, n as Payment, o as PaymentProvider } from "../../payments-CBzQIjoX.js";
+//#region src/blocks/donations/donations.d.ts
+type GiftStatus = "pending" | "posted" | "failed" | "refunded";
+type PledgeFrequency = "weekly" | "monthly" | "quarterly" | "yearly";
+type PledgeStatus = "active" | "paused" | "ended";
+interface DonationsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
+  /** Charges online gifts and pledge installments. */
+  readonly payments?: PaymentProvider;
+  /**
+   * A Standard Schema for the gift's extra columns
+   * (`blocks.donations.options.extraColumns`), keyed by database name. It types
+   * and parses them on reads, and validates them on `recordGift` and `give`.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Donations<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** A fund or campaign gifts go to. */
+interface DonationFund {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly key: string;
+  readonly name: string;
+  readonly kind: "fund" | "campaign";
+  readonly goal?: Money;
+  /** Posted gifts in the goal's currency; absent without a goal currency. */
+  readonly raised?: Money;
+  readonly startsOn?: Temporal.PlainDate;
+  readonly endsOn?: Temporal.PlainDate;
+  readonly archivedAt?: Temporal.Instant;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface DonationFundInput {
+  readonly key: string;
+  readonly name: string;
+  /** Default `fund`. */
+  readonly kind?: "fund" | "campaign";
+  readonly goal?: Money;
+  readonly startsOn?: Temporal.PlainDate;
+  readonly endsOn?: Temporal.PlainDate;
+}
+/** One gift. A posted gift is on the ledger. `F` types the extra columns. */
+interface Gift<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly donor: SubjectRef;
+  readonly fundId?: string;
+  readonly pledgeId?: string;
+  /** The pledge period this gift pays. */
+  readonly periodStart?: Temporal.PlainDate;
+  readonly amount: Money;
+  readonly receivedOn: Temporal.PlainDate;
+  readonly method?: string;
+  readonly status: GiftStatus;
+  readonly provider?: string;
+  readonly paymentReference?: string;
+  readonly transactionId?: string;
+  readonly refundTransactionId?: string;
+  readonly receiptId?: string;
+  readonly note?: string;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+/** A gift received outside the payments provider: cash, a check, a transfer. */
+interface GiftInput<F extends object = Record<never, never>> {
+  readonly donor: SubjectRef;
+  readonly amount: Money;
+  readonly fundId?: string;
+  /** Default: today. */
+  readonly receivedOn?: Temporal.PlainDate;
+  readonly method?: string;
+  readonly note?: string;
+  /** The pledge installment this gift pays, with `periodStart`. */
+  readonly pledgeId?: string;
+  readonly periodStart?: Temporal.PlainDate;
+  /** The extra columns to set. */
+  readonly fields?: Partial<F>;
+}
+/** A gift charged through the payments provider. */
+interface GiveInput<F extends object = Record<never, never>> {
+  readonly donor: SubjectRef;
+  readonly amount: Money;
+  readonly fundId?: string;
+  readonly note?: string;
+  /** The provider's customer id. */
+  readonly customer?: string;
+  readonly description?: string;
+  readonly returnUrl?: string;
+  /** The extra columns to set. */
+  readonly fields?: Partial<F>;
+}
+interface GiveOutcome<F extends object = Record<never, never>> {
+  readonly gift: Gift<F>;
+  /** Hand `clientSecret` or `redirectUrl` to the donor when it needs action. */
+  readonly payment: Payment;
+}
+interface GiftListOptions {
+  readonly donor?: SubjectRef;
+  readonly fundId?: string;
+  readonly pledgeId?: string;
+  readonly status?: GiftStatus;
+  readonly pageSize?: number;
+}
+/** A recurring gift. */
+interface Pledge {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly donor: SubjectRef;
+  readonly fundId?: string;
+  readonly amount: Money;
+  readonly frequency: PledgeFrequency;
+  readonly startsOn: Temporal.PlainDate;
+  readonly endsOn?: Temporal.PlainDate;
+  readonly status: PledgeStatus;
+  /** The payments provider that charges it; absent: recorded by hand. */
+  readonly provider?: string;
+  readonly providerCustomer?: string;
+  readonly note?: string;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface PledgeInput {
+  readonly donor: SubjectRef;
+  /** Per period. */
+  readonly amount: Money;
+  /** Default `monthly`. */
+  readonly frequency?: PledgeFrequency;
+  readonly fundId?: string;
+  /** Default: today. */
+  readonly startsOn?: Temporal.PlainDate;
+  readonly endsOn?: Temporal.PlainDate;
+  /** The payments provider's `name`, for `chargeDuePledges`. */
+  readonly provider?: string;
+  readonly providerCustomer?: string;
+  readonly note?: string;
+}
+interface PledgeUpdate {
+  readonly status?: PledgeStatus;
+  readonly endsOn?: Temporal.PlainDate;
+  /** For installments that have no gift yet. */
+  readonly amount?: Money;
+}
+interface PledgeListOptions {
+  readonly donor?: SubjectRef;
+  readonly status?: PledgeStatus;
+  readonly pageSize?: number;
+}
+/** A pledge period that has no gift yet. */
+interface PledgeInstallment {
+  readonly pledgeId: string;
+  readonly periodStart: Temporal.PlainDate;
+  readonly donor: SubjectRef;
+  readonly fundId?: string;
+  readonly amount: Money;
+  readonly provider?: string;
+  readonly providerCustomer?: string;
+}
+interface DueInstallmentOptions {
+  /** Default: today. Periods that start on or before it are due. */
+  readonly through?: Temporal.PlainDate;
+  /** Default 500. */
+  readonly maxRows?: number;
+}
+/** What `chargeDuePledges` did with one installment. */
+type PledgeChargeOutcome<F extends object = Record<never, never>> = {
+  readonly kind: "charged";
+  readonly installment: PledgeInstallment;
+  readonly gift: Gift<F>;
+} | {
+  readonly kind: "skipped";
+  readonly installment: PledgeInstallment;
+  readonly reason: string;
+} | {
+  readonly kind: "failed";
+  readonly installment: PledgeInstallment;
+  readonly error: DbError;
+};
+/** A numbered tax receipt. */
+interface DonationReceipt {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly donor: SubjectRef;
+  readonly sequence: bigint;
+  readonly number: string;
+  readonly kind: "gift" | "yearly";
+  readonly year: number;
+  readonly amount: Money;
+  readonly issuedAt: Temporal.Instant;
+  readonly voidedAt?: Temporal.Instant;
+  readonly voidReason?: string;
+}
+interface ReceiptListOptions {
+  readonly donor?: SubjectRef;
+  readonly year?: number;
+  readonly pageSize?: number;
+}
+/** A donor's posted giving in one year. */
+interface GivingSummary {
+  readonly year: number;
+  readonly donor: SubjectRef;
+  readonly totals: readonly {
+    readonly amount: Money;
+    readonly gifts: number;
+  }[];
+  readonly funds: readonly {
+    readonly fundId?: string;
+    readonly name: string;
+    readonly amount: Money;
+  }[];
+  readonly receipts: readonly DonationReceipt[];
+}
+/** What `webhook` and `handlePaymentEvent` did with an event. */
+type DonationPaymentOutcome<F extends object = Record<never, never>> = {
+  readonly event: string;
+  readonly kind: "gift";
+  readonly gift: Gift<F>;
+} | {
+  readonly event: string;
+  readonly kind: "ignored";
+  readonly reason: string;
+};
+interface Donations<F extends object = Record<never, never>> {
+  /** Creates or updates the fund with this key. Needs `donations.manage`. */
+  saveFund(input: DonationFundInput): AsyncResult<DonationFund>;
+  archiveFund(fundId: string): AsyncResult<DonationFund>;
+  funds(options?: {
+    readonly includeArchived?: boolean;
+  }): AsyncResult<readonly DonationFund[]>;
+  /** Records a gift received outside the provider and posts it at once. */
+  recordGift(input: GiftInput<F>): AsyncResult<Gift<F>>;
+  /**
+   * Opens a pending gift and charges it through the payments provider. The gift
+   * posts when the payment succeeds, here or from the webhook.
+   */
+  give(input: GiveInput<F>): AsyncResult<GiveOutcome<F>>;
+  getGift(giftId: string): AsyncResult<Gift<F>>;
+  gifts(options?: GiftListOptions): AsyncResult<readonly Gift<F>[]>;
+  createPledge(input: PledgeInput): AsyncResult<Pledge>;
+  updatePledge(pledgeId: string, update: PledgeUpdate): AsyncResult<Pledge>;
+  pledges(options?: PledgeListOptions): AsyncResult<readonly Pledge[]>;
+  dueInstallments(options?: DueInstallmentOptions): AsyncResult<readonly PledgeInstallment[]>;
+  /**
+   * Charges every due installment of pledges this provider charges, once per
+   * period: a second run reuses the period's gift and idempotency key.
+   */
+  chargeDuePledges(options?: DueInstallmentOptions): AsyncResult<readonly PledgeChargeOutcome<F>[]>;
+  /** Applies a provider event to its gift. */
+  handlePaymentEvent(event: PaymentEvent): AsyncResult<DonationPaymentOutcome<F>>;
+  /** Verifies a provider webhook and applies its events. */
+  webhook(input: WebhookInput): AsyncResult<readonly DonationPaymentOutcome<F>[]>;
+  /** A numbered receipt for one posted gift. */
+  issueGiftReceipt(giftId: string): AsyncResult<DonationReceipt>;
+  /** A donor's receipt for their posted gifts in a year and currency. */
+  issueYearlyReceipt(donor: SubjectRef, year: number, currency: string): AsyncResult<DonationReceipt>;
+  voidReceipt(receiptId: string, reason?: string): AsyncResult<DonationReceipt>;
+  receipts(options?: ReceiptListOptions): AsyncResult<readonly DonationReceipt[]>;
+  /** Default year: this one. */
+  givingSummary(donor: SubjectRef, year?: number): AsyncResult<GivingSummary>;
+}
+/** The `donations` SQL module as typed calls. */
+export declare function createDonations<S extends StandardSchemaV1 | undefined = undefined>(options: DonationsOptions<S>): Donations<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/donations/events.d.ts
+/** A gift as its events carry it. */
+interface DonationEventData {
+  readonly organizationId: string;
+  readonly id: string;
+  readonly donorType: string;
+  readonly donorId: string;
+  readonly fundId: string | null;
+  readonly pledgeId: string | null;
+  /** Minor units, as text. */
+  readonly amount: string;
+  readonly currency: string;
+  readonly status: "pending" | "posted" | "failed" | "refunded";
+}
+/** A pledge as its events carry it. */
+interface PledgeEventData {
+  readonly organizationId: string;
+  readonly id: string;
+  readonly donorType: string;
+  readonly donorId: string;
+  readonly fundId: string | null;
+  /** Minor units per period, as text. */
+  readonly amount: string;
+  readonly currency: string;
+  readonly frequency: "weekly" | "monthly" | "quarterly" | "yearly";
+  readonly status: "active" | "paused" | "ended";
+}
+/** A tax receipt as its events carry it. */
+interface DonationReceiptEventData {
+  readonly organizationId: string;
+  readonly id: string;
+  readonly number: string;
+  readonly kind: "gift" | "yearly";
+  readonly donorType: string;
+  readonly donorId: string;
+  readonly amount: string;
+  readonly currency: string;
+}
+/** The events of the `donations` block: type to data. */
+type DonationsEvents = {
+  readonly "donation.received": DonationEventData;
+  readonly "donation.failed": DonationEventData;
+  readonly "donation.refunded": DonationEventData;
+  readonly "pledge.created": PledgeEventData;
+  readonly "pledge.updated": PledgeEventData;
+  readonly "donation_receipt.issued": DonationReceiptEventData;
+  readonly "donation_receipt.voided": DonationReceiptEventData;
+};
+/** The `donations` block's event types, for its manifest and `onBlockEvent`. */
+export declare const donationsEvents: Events<DonationsEvents>;
+//#endregion
+//#region src/blocks/donations/section.d.ts
+/** A donor's giving this year, such as a contact's: totals, funds and receipts. */
+export declare const givingSection: Section<Donations, GivingSummary>;
+//#endregion
+//#region src/blocks/donations/manifest.d.ts
+/** The `donations` block's manifest (ADR 0029). */
+export declare const donationsBlock: BlockOf<"donations", typeof createDonations, DonationsEvents, Record<never, never>, never, {
+  readonly giving: typeof givingSection;
+}>;
+//#endregion
+//#region src/blocks/donations/schemas.d.ts
+/** What `recordGift` takes, with the bounds the SQL checks. */
+export declare const giftInputSchema: EntitySchema<GiftInput>;
+/** What `createPledge` takes. */
+export declare const pledgeInputSchema: EntitySchema<PledgeInput>;
+/** What `saveFund` takes. */
+export declare const donationFundInputSchema: EntitySchema<DonationFundInput>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type DonationEventData, type DonationFund, type DonationFundInput, type DonationPaymentOutcome, type DonationReceipt, type DonationReceiptEventData, type Donations, type DonationsEvents, type DonationsOptions, type DueInstallmentOptions, type Gift, type GiftInput, type GiftListOptions, type GiftStatus, type GiveInput, type GiveOutcome, type GivingSummary, type Pledge, type PledgeChargeOutcome, type PledgeEventData, type PledgeFrequency, type PledgeInput, type PledgeInstallment, type PledgeListOptions, type PledgeStatus, type PledgeUpdate, type ReceiptListOptions, type RpcClient, dbTransport, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };