@ar-agents/uala

Ualá Bis agent toolkit for the Vercel AI SDK 6+. Typed tools for payment links, QR cobros, transaction history, payouts, balance, and marketplace OAuth. Adapter pattern: pure-types + validation out of the box, real API behind a pluggable adapter.

pnpm add @ar-agents/uala

Quick start

import { Experimental_Agent as Agent } from "ai";
import { ualaTools, UalaApiAdapter } from "@ar-agents/uala";
import { anthropic } from "@ai-sdk/anthropic";

const tools = ualaTools({
  adapter: new UalaApiAdapter({ apiKey: process.env.UALA_API_KEY! }),
});

const agent = new Agent({
  model: anthropic("claude-sonnet-4-7"),
  tools,
  system: "You are a billing assistant for an Argentine SaaS.",
});

const result = await agent.generate({
  prompt: "Crear un link de cobro por ARS 1.500 con descripción 'plan mensual'.",
});

What you get

Eight tools, all returning typed responses:

| Tool | What it does | | ----------------------------- | ----------------------------------------------------- | | uala_create_payment_link | Create a shareable payment link (with optional QR). | | uala_get_payment_link | Poll a link's status. | | uala_cancel_payment_link | Revoke an open link. | | uala_list_transactions | List account movements with pagination. | | uala_get_transaction | Fetch a single transaction. | | uala_get_balance | Current available + pending balance. | | uala_create_payout | Initiate a payout to a CBU. Idempotency-keyed. | | uala_get_payout | Track payout status to completion. |

Adapter pattern

The tool layer never touches the network directly. It calls an UalaAdapter. The default is UnconfiguredUalaAdapter, which throws UalaUnconfiguredError on every call — safe for unit tests, fails loud in production if you forgot to wire credentials.

import { UalaApiAdapter } from "@ar-agents/uala";

const adapter = new UalaApiAdapter({
  apiKey: process.env.UALA_API_KEY!,
  // Optional. Override for sandbox / staging:
  baseUrl: "https://api.uala.com.ar/v1",
  // Optional. Custom fetch for tests, OTel, or custom timeouts:
  fetchImpl: fetch,
  timeoutMs: 10_000,
});

You can also bring your own adapter by implementing the UalaAdapter interface. Examples: in-memory mock for integration tests, a fake that simulates timeouts, a metered proxy in front of the real API.

Marketplace OAuth

For multi-merchant integrations, use the OAuth helpers (pure functions, no agent tools — the OAuth dance is server-driven by the host):

import { buildAuthorizeUrl, exchangeCodeForToken } from "@ar-agents/uala";

// Step 1: redirect the merchant.
const authorizeUrl = buildAuthorizeUrl({
  clientId: process.env.UALA_OAUTH_CLIENT_ID!,
  redirectUri: "https://yourapp.com/uala/callback",
  scope: ["payments.read", "payouts.write"],
  state: randomCsrfToken,
});

// Step 2: exchange code for token in your callback handler.
const tokens = await exchangeCodeForToken({
  clientId: process.env.UALA_OAUTH_CLIENT_ID!,
  clientSecret: process.env.UALA_OAUTH_CLIENT_SECRET!,
  redirectUri: "https://yourapp.com/uala/callback",
  code,
});
// Store tokens.accessToken, tokens.refreshToken, tokens.expiresAt per merchant.

Errors

All errors inherit from UalaError:

import {
  UalaError,
  UalaUnconfiguredError,
  UalaAuthError,
  UalaApiError,
  UalaValidationError,
} from "@ar-agents/uala";

try {
  await tools.uala_create_payout.execute({
    amount: 100000,
    destinationCbu: "0".repeat(22),
  });
} catch (e) {
  if (e instanceof UalaAuthError) /* re-auth */;
  else if (e instanceof UalaValidationError) /* bad input, do not retry */;
  else if (e instanceof UalaApiError) /* check e.status */;
  else throw e;
}

Constraints (quick reference)

• Amounts in centavos for ARS, cents for USD. No floats.
• CBU is 22 digits exactly.
• idempotencyKey honored for create_payment_link and create_payout.
• Currency defaults to ARS.
• 10-second hard timeout per request.

For LLM agents using these tools, see AGENTS.md.

License

MIT — Nazareno Clemente [email protected]