Package com.tnsai.tools.fintech

Class PaymentAnalyticsTools

java.lang.Object

com.tnsai.tools.fintech.PaymentAnalyticsTools

public class PaymentAnalyticsTools
extends Object

Function-shape payment-analytics tool — the LangChain-style replacement for the legacy PaymentAnalyticsTool. The legacy tool returned hard-coded simulated data ($12,450.00 daily revenue, etc.); this POJO computes real aggregates by composing existing payment-provider POJOs.

Composition

Today the only data source is SquareTools via its square_list_payments method. The aggregator pulls the raw payment list, sums by status, computes per-currency totals, and surfaces an LLM- friendly summary. Adding another provider (Stripe, PayPal, …) is a matter of injecting another POJO and unioning its results — the public method shape stays the same.

One typed @Tool method:

Method	Source	Idempotent
paymentRevenueSummary(java.lang.String, java.lang.String, java.lang.String)	SquareTools.squareListPayments	✓ (read-only aggregate)

Since:

0.5.7 (Phase 2 batch 7e — built-in tool migration to function shape, see #188)

Constructor Summary

Constructors

Constructor	Description
PaymentAnalyticsTools()	Default constructor — wires a no-arg SquareTools (which itself pulls credentials from SQUARE_ACCESS_TOKEN + SQUARE_LOCATION_ID).
PaymentAnalyticsTools(SquareTools squareTools)	Explicit-composition constructor — preferred when the consumer already built and configured a SquareTools instance.

Method Summary

Modifier and Type	Method	Description
Map<String,Object>	paymentRevenueSummary(String since, String until, String locationId)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

PaymentAnalyticsTools

public PaymentAnalyticsTools()

Default constructor — wires a no-arg SquareTools (which itself pulls credentials from SQUARE_ACCESS_TOKEN + SQUARE_LOCATION_ID). Suitable for Role.tools() in agents that already include new SquareTools().

PaymentAnalyticsTools

public PaymentAnalyticsTools(SquareTools squareTools)

Explicit-composition constructor — preferred when the consumer already built and configured a SquareTools instance. Sharing a single SquareTools across both POJOs avoids constructing two HTTP clients.

Method Details

paymentRevenueSummary

@Tool(name="payment_revenue_summary",
      description="Aggregate revenue and transaction stats from real payment-provider data within a date range. Currently pulls from Square (capped at 100 transactions per call \u2014 for longer ranges, query in shorter windows and sum). Returns {since, until, totalCount, completedCount, totalAmountCents, averageAmountCents, currency, byStatus}. Read-only. Times are ISO-8601 (e.g. \"2026-01-01T00:00:00Z\"); blank values default to the past 24 hours.",
      keywords={"payment","revenue","analytics","summary","report","dashboard"},
      idempotent=true)
public Map<String,Object> paymentRevenueSummary(@ToolParam(description="ISO-8601 lower bound (inclusive); blank = 24h ago",required=false,defaultValue="")
 String since,
 @ToolParam(description="ISO-8601 upper bound (exclusive); blank = now",required=false,defaultValue="")
 String until,
 @ToolParam(description="Restrict to a single Square location id; blank = all locations",required=false,defaultValue="")
 String locationId)
                                         throws IOException

Throws:

IOException