@fabriktor/fx 0.0.130 → 0.0.132

package/dist/src/payments/payments.d.ts

@@ -1,4 +1,4 @@
-import { PaymentEntityTypeBill, PaymentEntityTypePayroll, type Bill, type Payroll, PSPPaymentStatusPending, PSPPaymentStatusPartial, PSPPaymentStatusFull, type CreditLedgerEntry, type Payment, type PmtAccount, type PmtBankAccount, type PmtCard, type PmtCustomer, type PmtPublicSession, type PmtRefund } from "@fabriktor/schema";
+import { PaymentEntityTypeBill, PaymentEntityTypePayroll, type Bill, type Payroll, PSPPaymentStatusPending, PSPPaymentStatusPartial, PSPPaymentStatusFull, type CreditLedgerEntry, type Payment, type PmtAccount, type PmtBankAccount, type PmtCard, type PmtCustomer, type PmtPublicSession, type PmtRefund, type SortStripeBalanceResult } from "@fabriktor/schema";
 import { type PaymentsOperator, type BillableOperator, type PayrollsOperator } from "@fabriktor/client";
 import { type SearchOptions, type OwnerSearchOptions, type SearchPage } from "../core/search.js";
 import { EventBus } from "../core/events.js";
@@ -86,11 +86,23 @@ export type CreateEntityPaymentOptions = {
 };
 export type CreatePaymentOptions = PaymentInsertOptions & MultiCreateCheckpoint;
 export type ReplacePaymentOptions = PaymentReplaceOptions;
-export type SearchPaymentsOptions = OwnerSearchOptions & {
+export type PaymentSearchFilters = {
     type?: Payment["type"] | Payment["type"][];
     kind?: Payment["kind"];
+    psp_actionable_status?: Payment["psp_actionable_status"][];
+    currency?: string;
 };
+export type SearchPaymentsOptions = SearchOptions & EntityPaymentScope & PaymentSearchFilters;
 export type SearchPaymentsPage = SearchPage<Payment>;
+export declare const PaymentDirection: {
+    readonly Outgoing: "outgoing";
+    readonly Incoming: "incoming";
+};
+export type PaymentDirection = (typeof PaymentDirection)[keyof typeof PaymentDirection];
+export type SearchPaymentHistoryOptions = OwnerSearchOptions & PaymentSearchFilters & {
+    direction: PaymentDirection;
+};
+export declare function isIncomingPayment(payment: Payment, viewerID: string): boolean;
 export type CreatePmtAccountOptions = PmtAccountInsertOptions;
 export type ContinuePmtAccountOnboardingOptions = PmtAccountOnboardingOptions;
 export type ContinuePmtAccountOnboardingResult = string;
@@ -137,6 +149,11 @@ export type GetPmtAccountAccessOptions = {
     owner_id: string;
     signal?: AbortSignal;
 };
+export type GetPayoutBalanceOptions = GetPmtAccountAccessOptions;
+export type PayoutBalance = {
+    access: PmtAccountAccess;
+    balance: SortStripeBalanceResult | null;
+};
 export declare function isPmtAccountReady(account: PmtAccount | null): boolean;
 export declare function currentPmtAccount(accounts: readonly PmtAccount[]): PmtAccount | null;
 export declare function pmtAccountAccess(account: PmtAccount | null): PmtAccountAccess;
@@ -182,11 +199,13 @@ export interface PaymentsFXOperator {
     createPayment(opts: CreatePaymentOptions): Promise<Payment>;
     replacePayment(opts: ReplacePaymentOptions): Promise<Payment>;
     searchPayments(opts: SearchPaymentsOptions): Promise<SearchPaymentsPage>;
+    searchPaymentHistory(opts: SearchPaymentHistoryOptions): Promise<SearchPaymentsPage>;
     createPmtAccount(opts: CreatePmtAccountOptions): Promise<PmtAccount>;
     continuePmtAccountOnboarding(opts: ContinuePmtAccountOnboardingOptions): Promise<ContinuePmtAccountOnboardingResult>;
     replacePmtAccount(opts: ReplacePmtAccountOptions): Promise<PmtAccount>;
     searchPmtAccounts(opts: SearchPmtAccountsOptions): Promise<SearchPmtAccountsPage>;
     getPmtAccountAccess(opts: GetPmtAccountAccessOptions): Promise<PmtAccountAccess>;
+    getPayoutBalance(opts: GetPayoutBalanceOptions): Promise<PayoutBalance>;
     createPmtBankAccount(opts: CreatePmtBankAccountOptions): Promise<PmtBankAccount>;
     replacePmtBankAccount(opts: ReplacePmtBankAccountOptions): Promise<PmtBankAccount>;
     searchPmtBankAccounts(opts: SearchPmtBankAccountsOptions): Promise<SearchPmtBankAccountsPage>;
@@ -228,11 +247,13 @@ export declare class PaymentsFX implements PaymentsFXOperator {
     createPayment(opts: CreatePaymentOptions): Promise<Payment>;
     replacePayment(opts: ReplacePaymentOptions): Promise<Payment>;
     searchPayments(opts: SearchPaymentsOptions): Promise<SearchPaymentsPage>;
+    searchPaymentHistory(opts: SearchPaymentHistoryOptions): Promise<SearchPaymentsPage>;
     createPmtAccount(opts: CreatePmtAccountOptions): Promise<PmtAccount>;
     continuePmtAccountOnboarding(opts: ContinuePmtAccountOnboardingOptions): Promise<ContinuePmtAccountOnboardingResult>;
     replacePmtAccount(opts: ReplacePmtAccountOptions): Promise<PmtAccount>;
     searchPmtAccounts(opts: SearchPmtAccountsOptions): Promise<SearchPmtAccountsPage>;
     getPmtAccountAccess(opts: GetPmtAccountAccessOptions): Promise<PmtAccountAccess>;
+    getPayoutBalance(opts: GetPayoutBalanceOptions): Promise<PayoutBalance>;
     createPmtBankAccount(opts: CreatePmtBankAccountOptions): Promise<PmtBankAccount>;
     replacePmtBankAccount(opts: ReplacePmtBankAccountOptions): Promise<PmtBankAccount>;
     searchPmtBankAccounts(opts: SearchPmtBankAccountsOptions): Promise<SearchPmtBankAccountsPage>;

package/dist/src/payments/payments.js

@@ -14,6 +14,7 @@ const publicAmountPattern = /^\d+$/;
 const resourcePayment = "payment";
 const resourcePmtAccount = "pmt_account";
 const resourcePmtAccountOnboarding = "pmt_account_onboarding";
+const resourcePayoutBalance = "payout_balance";
 const resourcePmtBankAccount = "pmt_bank_account";
 const resourcePmtCard = "pmt_card";
 const resourcePmtRefund = "pmt_refund";
@@ -26,7 +27,7 @@ const msgPayableSourceMissing = "Payable entity source is unavailable.";
 const msgPayableBalanceChanged = "Payment balance changed or a payment is still pending. Refresh before paying.";
 const msgPaymentMethodRequired = "A payment method is required.";
 const msgPayableUnavailable = "This entity is not available for payment.";
-const msgPaymentScopeMissing = "Payment history requires a payer or recipient scope and an entity type.";
+const msgPaymentScopeMissing = "Payment history requires a payer or recipient scope.";
 const msgPaymentHistoryIncomplete = "Payment history response is incomplete.";
 const msgPaymentEntityInvalid = "Payment resolution requires a valid entity, currency, and amount.";
 const msgPaymentEntityConflict = "Payment resolution received conflicting entity amounts.";
@@ -37,6 +38,7 @@ const msgCreatedPaymentIDMissing = "Created payment response did not contain an
 const msgPaymentMissing = "Payment could not be resolved after the mutation.";
 const msgCreatedPmtAccountIDMissing = "Created payment account response did not contain an ID.";
 const msgPmtAccountMissing = "Payment account could not be resolved after the mutation.";
+const msgPayoutBalanceMissing = "Payout balance response is incomplete.";
 const msgPmtAccountOnboardingIDMissing = "Payment account onboarding requires a valid account ID.";
 const msgPmtAccountOnboardingLinkMissing = "Payment account onboarding did not return a link.";
 const msgCreatedPmtBankAccountIDMissing = "Created payment bank account response did not contain an ID.";
@@ -63,6 +65,14 @@ const msgPublicAmountExceedsBalance = "Public payment amount cannot exceed the s
 export const PaymentsEvents = {
     Changed: createEvent(),
 };
+export const PaymentDirection = {
+    Outgoing: "outgoing",
+    Incoming: "incoming",
+};
+export function isIncomingPayment(payment, viewerID) {
+    return (payment.recipient_id === viewerID &&
+        (payment.is_external || payment.payer_id !== viewerID));
+}
 export const PmtAccountAccessStatus = {
     Missing: "missing",
     OnboardingRequired: "onboarding_required",
@@ -390,12 +400,57 @@ export class PaymentsFX {
         return payment;
     }
     async searchPayments(opts) {
-        return await runOwnerSearch({
+        const owner_id = resolvedID(opts.owner_id);
+        const recipient_id = resolvedID(opts.recipient_id);
+        if (!owner_id && !recipient_id)
+            throw errValidation({ msg: msgPaymentScopeMissing });
+        return await runSearch({
             ...opts,
-            query: queryParams({ type: opts.type, kind: opts.kind }),
+            query: queryParams({
+                owner_id,
+                recipient_id,
+                type: opts.type,
+                kind: opts.kind,
+                psp_actionable_status: opts.psp_actionable_status,
+                currency: opts.currency?.trim().toUpperCase() || undefined,
+            }),
             search: (searchOpts) => this.payments.searchManyPayments(searchOpts),
         });
     }
+    async searchPaymentHistory(opts) {
+        const { owner_id, direction, ...searchOpts } = opts;
+        const viewer = resolvedID(owner_id);
+        if (!viewer)
+            throw errValidation({ msg: msgPaymentScopeMissing });
+        const incoming = direction === PaymentDirection.Incoming;
+        let page = opts.page;
+        while (true) {
+            opts.signal?.throwIfAborted();
+            const out = await this.searchPayments({
+                ...searchOpts,
+                ...(incoming ? { recipient_id: viewer } : { owner_id: viewer }),
+                page,
+            });
+            // Public bill payments belong to their recipient. Ownership alone does
+            // not make them outgoing; scan source pages without changing their order.
+            const results = out.results.filter((payment) => isIncomingPayment(payment, viewer) === incoming);
+            if (results.length || out.done) {
+                return {
+                    ...out,
+                    results,
+                    total_count: undefined,
+                    last_page: undefined,
+                };
+            }
+            if (out.next_page <= out.page) {
+                throw errResolveFailed({
+                    resource: resourcePayment,
+                    msg: msgPaymentHistoryIncomplete,
+                });
+            }
+            page = out.next_page;
+        }
+    }
     async createPmtAccount(opts) {
         const out = await this.payments.insertOnePmtAccount(opts);
         const id = requiredOperationID(out, msgCreatedPmtAccountIDMissing);
@@ -449,6 +504,31 @@ export class PaymentsFX {
             page = out.next_page;
         }
     }
+    async getPayoutBalance(opts) {
+        const access = await this.getPmtAccountAccess(opts);
+        opts.signal?.throwIfAborted();
+        const accountID = resolvedID(access.account?.psp_id);
+        if (accountID === undefined) {
+            return { access, balance: null };
+        }
+        // Outstanding funds remain visible when the account needs updated onboarding.
+        const out = await this.payments.balance({ psp_account_id: accountID }, { signal: opts.signal });
+        opts.signal?.throwIfAborted();
+        if (!out?.value) {
+            throw errResolveFailed({
+                resource: resourcePayoutBalance,
+                msg: msgPayoutBalanceMissing,
+            });
+        }
+        return {
+            access,
+            balance: {
+                available: out.value.available ?? [],
+                pending: out.value.pending ?? [],
+                instant_available: out.value.instant_available ?? [],
+            },
+        };
+    }
     async createPmtBankAccount(opts) {
         const out = await this.payments.insertOnePmtBankAccount(opts);
         const id = requiredOperationID(out, msgCreatedPmtBankAccountIDMissing);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabriktor/fx",
-  "version": "0.0.130",
+  "version": "0.0.132",
   "description": "![Fabriktor Logo](./img/fabriktor-character.gif)",
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@fabriktor/client": "0.0.92",
+    "@fabriktor/client": "0.0.93",
     "@fabriktor/fx": "0.0.94",
     "@fabriktor/schema": "0.0.66"
   }