@elizaos/plugin-finances 2.0.3-beta.6 → 2.0.3-beta.7

package/dist/finances-service.d.ts

@@ -0,0 +1,179 @@
+/**
+ * FinancesService — the finance back-end (payment sources, transactions,
+ * spending summaries, recurring-charge detection, email bills, and the
+ * Plaid / PayPal managed bridges).
+ *
+ * This is the standalone successor to the `withPayments` LifeOps service
+ * mixin. It holds its own runtime + {@link FinancesRepository} and the small
+ * identity / logging helpers the methods need, so it has no dependency on
+ * `@elizaos/plugin-personal-assistant`. Behavior and the data it returns are
+ * preserved verbatim from the original mixin.
+ *
+ * Subscription audit / cancellation lives in the sibling
+ * `./services/subscriptions-service.ts` (`SubscriptionsService`), which reaches
+ * Gmail + the browser bridge through runtime-service seams.
+ */
+import { type IAgentRuntime } from "@elizaos/core";
+import { PaypalManagedClient, type PaypalTransactionDto, PlaidManagedClient, type PlaidTransactionDto } from "@elizaos/plugin-elizacloud/cloud/managed-payment-clients";
+import { FinancesRepository } from "./db/finances-repository.js";
+import type { AddPaymentSourceRequest, ImportTransactionsCsvRequest, ImportTransactionsCsvResult, LifeOpsPaymentSource, LifeOpsPaymentsDashboard, LifeOpsPaymentTransaction, LifeOpsRecurringCharge, LifeOpsSpendingSummary, LifeOpsUpcomingBill, ListTransactionsRequest, SpendingSummaryRequest } from "./payment-types.js";
+import { type EncryptedTokenEnvelope } from "./token-encryption.js";
+/** Optional construction options (mirrors the LifeOps service shape). */
+export type FinancesServiceOptions = {
+    ownerEntityId?: string | null;
+};
+export declare function encryptPaymentMetadataToken(token: string, env?: NodeJS.ProcessEnv): EncryptedTokenEnvelope;
+export declare function readPaymentMetadataToken(value: unknown, field: string, env?: NodeJS.ProcessEnv): string | null;
+export declare function sanitizePaymentSourceForClient(source: LifeOpsPaymentSource): LifeOpsPaymentSource;
+export declare class FinancesService {
+    readonly runtime: IAgentRuntime;
+    readonly repository: FinancesRepository;
+    readonly ownerEntityId: string | null;
+    plaidManagedClientCache: PlaidManagedClient | null;
+    paypalManagedClientCache: PaypalManagedClient | null;
+    constructor(runtime: IAgentRuntime, options?: FinancesServiceOptions);
+    agentId(): string;
+    private logFinancesWarn;
+    listPaymentSources(): Promise<LifeOpsPaymentSource[]>;
+    addPaymentSource(request: AddPaymentSourceRequest): Promise<LifeOpsPaymentSource>;
+    deletePaymentSource(sourceId: string): Promise<{
+        ok: true;
+    }>;
+    importTransactionsCsv(request: ImportTransactionsCsvRequest): Promise<ImportTransactionsCsvResult>;
+    listTransactions(request?: ListTransactionsRequest): Promise<LifeOpsPaymentTransaction[]>;
+    getRecurringCharges(args?: {
+        sourceId?: string | null;
+        sinceDays?: number | null;
+    }): Promise<LifeOpsRecurringCharge[]>;
+    getSpendingSummary(request?: SpendingSummaryRequest): Promise<LifeOpsSpendingSummary>;
+    getPaymentsDashboard(args?: {
+        windowDays?: number | null;
+    }): Promise<LifeOpsPaymentsDashboard>;
+    /**
+     * Look up the singleton "Email bills" payment source for this agent,
+     * creating it on first use. Bills detected from email are persisted
+     * against this source so the existing transactions table can carry them
+     * without a parallel schema.
+     */
+    getOrCreateEmailPaymentSource(): Promise<LifeOpsPaymentSource>;
+    /**
+     * Idempotent insert of a bill extracted from an email. The transaction
+     * id is derived from `(agent, sourceId, sourceMessageId)` so re-ingesting
+     * the same Gmail message never creates a duplicate row.
+     */
+    upsertBillFromEmail(args: {
+        sourceMessageId: string;
+        merchant: string;
+        amountUsd: number;
+        currency: string;
+        dueDate: string | null;
+        postedAt?: string | null;
+        confidence: number;
+    }): Promise<{
+        inserted: boolean;
+        transactionId: string;
+    }>;
+    /**
+     * Mark a previously-extracted bill as paid. Idempotent — repeated calls
+     * just re-stamp the metadata. The row itself is not deleted so the
+     * transaction history stays intact.
+     */
+    markBillPaid(args: {
+        billId: string;
+        paidAt?: string | null;
+    }): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Push a bill's due date out by N days. Used for "Snooze 1w" UI.
+     */
+    snoozeBill(args: {
+        billId: string;
+        days: number;
+    }): Promise<{
+        ok: true;
+        dueDate: string;
+    }>;
+    /**
+     * Read bills extracted from email. This includes overdue and no-date bills
+     * so extraction misses do not disappear from the user's review queue.
+     */
+    getUpcomingBills(args?: {
+        now?: Date;
+    }): Promise<LifeOpsUpcomingBill[]>;
+    summarizePaymentsDashboard(dashboard: LifeOpsPaymentsDashboard): string;
+    getPlaidManagedClient(): PlaidManagedClient;
+    /** Returns a Plaid Link token for the frontend to drive the Plaid Link UI. */
+    createPlaidLinkToken(): Promise<{
+        linkToken: string;
+        expiration: string;
+        environment: string;
+    }>;
+    /**
+     * Completes a Plaid Link flow by exchanging the public_token for an
+     * access_token and creating (or updating) a payment_source row whose
+     * metadata holds the access_token + cursor for sync.
+     */
+    completePlaidLink(args: {
+        publicToken: string;
+        label?: string | null;
+    }): Promise<LifeOpsPaymentSource>;
+    /**
+     * Pulls the latest transaction delta for a Plaid-backed source and
+     * inserts the new rows into life_payment_transactions.
+     */
+    syncPlaidTransactions(args: {
+        sourceId: string;
+    }): Promise<{
+        inserted: number;
+        skipped: number;
+        nextCursor: string;
+    }>;
+    getPaypalManagedClient(): PaypalManagedClient;
+    /** Returns a PayPal Login URL the frontend should open in a popup. */
+    createPaypalAuthorizeUrl(args: {
+        state: string;
+    }): Promise<{
+        url: string;
+        scope: string;
+        environment: "live" | "sandbox";
+    }>;
+    /**
+     * Completes the PayPal OAuth flow by exchanging the authorization code
+     * for tokens, then creating a payment_source row keyed to the PayPal
+     * payer. The access_token + refresh_token are stored in source.metadata
+     * so the runtime can refresh on demand without re-prompting the user.
+     */
+    completePaypalLink(args: {
+        code: string;
+        label?: string | null;
+    }): Promise<{
+        source: LifeOpsPaymentSource;
+        capability: {
+            hasReporting: boolean;
+            hasIdentity: boolean;
+        };
+    }>;
+    /**
+     * Pulls PayPal transactions for a date window via the Reporting API.
+     * Returns the imported count and an explicit `fallback: "csv_export"`
+     * flag when the account is personal-tier.
+     */
+    syncPaypalTransactions(args: {
+        sourceId: string;
+        windowDays?: number | null;
+    }): Promise<{
+        inserted: number;
+        skipped: number;
+        fallback: "csv_export" | null;
+    }>;
+    upsertPaypalTransaction(args: {
+        sourceId: string;
+        transaction: PaypalTransactionDto;
+    }): Promise<boolean>;
+    upsertPlaidTransaction(args: {
+        sourceId: string;
+        transaction: PlaidTransactionDto;
+    }): Promise<boolean>;
+}
+//# sourceMappingURL=finances-service.d.ts.map

package/dist/finances-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finances-service.d.ts","sourceRoot":"","sources":["../src/finances-service.ts"],"names":[],"mappings":"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"}