Package com.tnsai.tools.fintech

Class SquareTools

java.lang.Object

com.tnsai.tools.fintech.SquareTools

public class SquareTools
extends Object

Function-shape Square tools — the LangChain-style replacement for the legacy SquarePaymentTool, SquareInvoiceTool, SquareCatalogTool, and SquareCustomerTool. See issue #188.

Five typed @Tool methods covering the Square API operations that show up in payment / commerce agent flows. Each legacy tool exposed 5+ operations (create / get / list / update / delete / search) — this migration covers the most-common one per resource. Niche ops (refund, cancel, update, delete) can be added piecewise as real consumers need them.

Method	Endpoint	Idempotent
squareCreatePayment(long, java.lang.String, java.lang.String, java.lang.String, java.lang.String)	POST /v2/payments	✓ (idempotency_key)
squareListPayments(java.lang.String, java.lang.String, java.lang.String, int)	GET /v2/payments	✓
squareCreateInvoice(java.lang.String, long, java.lang.String, java.lang.String, java.lang.String)	POST /v2/invoices	✓ (idempotency_key)
squareCreateCustomer(java.lang.String, java.lang.String, java.lang.String, java.lang.String)	POST /v2/customers	✓ (idempotency_key)
squareSearchCatalog(java.lang.String, int)	POST /v2/catalog/search	✓

Square uses idempotency keys (UUIDs) on every write operation — calling a create method twice with the same key yields the same payment / invoice / customer instead of duplicates. The framework generates a fresh UUID per call; if the same logical operation needs to be retried with the same key, the consumer must wrap with their own retry layer.

Sandbox

Set the useSandbox constructor flag (or SQUARE_SANDBOX=true env var) to route requests through connect.squareupsandbox.com instead of production. Always develop against sandbox.

Since:

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

Constructor Summary

Constructors

Constructor	Description
SquareTools()	Default constructor — reads SQUARE_ACCESS_TOKEN, SQUARE_LOCATION_ID, and SQUARE_SANDBOX=true|false from env.
SquareTools(String accessToken)	Explicit-credentials constructor (no default location).
SquareTools(String accessToken, String defaultLocationId)	Explicit access token + default location id (most consumers want this).
SquareTools(String accessToken, String defaultLocationId, boolean useSandbox, okhttp3.OkHttpClient http, com.fasterxml.jackson.databind.ObjectMapper mapper)	Full constructor — useful for tests or sandbox routing.

Method Summary

Modifier and Type	Method	Description
Map<String,Object>	squareCreateCustomer(String givenName, String familyName, String emailAddress, String phoneNumber)
Map<String,Object>	squareCreateInvoice(String customerId, long amountCents, String currency, String locationId, String title)
Map<String,Object>	squareCreatePayment(long amountCents, String currency, String sourceId, String locationId, String note)
Map<String,Object>	squareListPayments(String beginTime, String endTime, String locationId, int limit)
Map<String,Object>	squareSearchCatalog(String query, int limit)

Methods inherited from class java.lang.Object

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

Constructor Details

SquareTools

public SquareTools()

Default constructor — reads SQUARE_ACCESS_TOKEN, SQUARE_LOCATION_ID, and SQUARE_SANDBOX=true|false from env.

SquareTools

public SquareTools(String accessToken)

Explicit-credentials constructor (no default location).

SquareTools

public SquareTools(String accessToken,
 String defaultLocationId)

Explicit access token + default location id (most consumers want this).

SquareTools

public SquareTools(String accessToken,
 String defaultLocationId,
 boolean useSandbox,
 okhttp3.OkHttpClient http,
 com.fasterxml.jackson.databind.ObjectMapper mapper)

Full constructor — useful for tests or sandbox routing.

Method Details

squareCreatePayment

@Tool(name="square_create_payment",
      description="DESTRUCTIVE: charge a payment via Square. {amountCents} is the amount in the smallest currency unit (e.g. 1000 = $10.00 USD). {sourceId} is the payment-source nonce from Square\'s web/mobile SDK or a card-on-file id. {locationId} defaults to SQUARE_LOCATION_ID. The call uses Square\'s idempotency_key \u2014 calling twice with the same arguments AND a retry of the same logical operation is an at-most-once write at Square\'s side. Returns {id, status, amount, currency, receiptUrl?}.",
      keywords={"square","payment","pay","charge","credit-card","fintech"},
      idempotent=true)
public Map<String,Object> squareCreatePayment(@ToolParam(description="Amount in the smallest currency unit (cents for USD/EUR; 1000 = $10.00)")
 long amountCents,
 @ToolParam(description="ISO 4217 currency code (e.g. \"USD\", \"EUR\", \"TRY\")",required=false,defaultValue="USD")
 String currency,
 @ToolParam(description="Payment source nonce from Square SDK (\"cnon:\u2026\") or saved card id (\"ccof:\u2026\")")
 String sourceId,
 @ToolParam(description="Square location id; blank uses SQUARE_LOCATION_ID",required=false,defaultValue="")
 String locationId,
 @ToolParam(description="Optional internal note for the merchant",required=false,defaultValue="")
 String note)
                                       throws IOException

Throws:

IOException

squareListPayments

@Tool(name="square_list_payments",
      description="List Square payments \u2014 read-only. Optional filters: {beginTime} / {endTime} (ISO-8601 timestamps), {locationId} (defaults to SQUARE_LOCATION_ID, blank = all locations), {limit} (1..100, default 50). Returns {count, payments[]}; each payment is {id, status, amount, currency, createdAt}.",
      keywords={"square","payments","list","history"},
      idempotent=true)
public Map<String,Object> squareListPayments(@ToolParam(description="ISO-8601 lower bound (e.g. \"2026-01-01T00:00:00Z\"); blank = no lower bound",required=false,defaultValue="")
 String beginTime,
 @ToolParam(description="ISO-8601 upper bound; blank = no upper bound",required=false,defaultValue="")
 String endTime,
 @ToolParam(description="Restrict to one Square location; blank = all locations",required=false,defaultValue="")
 String locationId,
 @ToolParam(description="Max results (1..100); 0 falls back to default 50",required=false,defaultValue="0")
 int limit)
                                      throws IOException

Throws:

IOException

squareCreateInvoice

@Tool(name="square_create_invoice",
      description="DESTRUCTIVE: create a Square invoice for a customer. {customerId} is a Square customer id (from square_create_customer). {amountCents} + {currency} specify the total. The invoice is created in DRAFT status \u2014 publish/send it via the Square Dashboard or a follow-up API call. {locationId} defaults to SQUARE_LOCATION_ID.",
      keywords={"square","invoice","create","billing","draft"},
      idempotent=true)
public Map<String,Object> squareCreateInvoice(@ToolParam(description="Square customer id (from square_create_customer)")
 String customerId,
 @ToolParam(description="Invoice total in smallest currency unit (cents)")
 long amountCents,
 @ToolParam(description="ISO 4217 currency code",required=false,defaultValue="USD")
 String currency,
 @ToolParam(description="Square location id; blank uses SQUARE_LOCATION_ID",required=false,defaultValue="")
 String locationId,
 @ToolParam(description="Optional invoice title shown to the customer",required=false,defaultValue="")
 String title)
                                       throws IOException

Throws:

IOException

squareCreateCustomer

@Tool(name="square_create_customer",
      description="DESTRUCTIVE: create a Square customer record. At least one of {givenName} / {familyName} / {emailAddress} / {phoneNumber} must be set; supplying everything yields the richest customer profile. Returns the new customer\'s {id, displayName, emailAddress, phoneNumber, createdAt}.",
      keywords={"square","customer","create","crm"},
      idempotent=true)
public Map<String,Object> squareCreateCustomer(@ToolParam(description="Customer\'s given (first) name",required=false,defaultValue="")
 String givenName,
 @ToolParam(description="Customer\'s family (last) name",required=false,defaultValue="")
 String familyName,
 @ToolParam(description="Customer\'s email address",required=false,defaultValue="")
 String emailAddress,
 @ToolParam(description="Customer\'s phone number (E.164: \"+15551234567\")",required=false,defaultValue="")
 String phoneNumber)
                                        throws IOException

Throws:

IOException

squareSearchCatalog

@Tool(name="square_search_catalog",
      description="Search the Square catalog (items / variations / categories / discounts / taxes) by free-text query. Returns the top {limit} matches with {id, type, name}. Read-only.",
      keywords={"square","catalog","search","item","product"},
      idempotent=true)
public Map<String,Object> squareSearchCatalog(@ToolParam(description="Free-text query against item / variation / category names")
 String query,
 @ToolParam(description="Max results (1..100); 0 falls back to default 50",required=false,defaultValue="0")
 int limit)
                                       throws IOException

Throws:

IOException