# @soledgic/ai

Pre-built Soledgic tools for the Vercel AI SDK. Give AI agents native access to
platform payments, wallet balances, creator payouts, and checkout sessions —
without writing any glue code.

## Installation

```bash
npm install @soledgic/ai @soledgic/sdk ai zod
```

## Usage

```ts
import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { soledgicTools } from '@soledgic/ai/vercel'

const result = await generateText({
  model: openai('gpt-4o'),
  // Read-only by default. Opt in to mutating tools explicitly:
  tools: soledgicTools({ apiKey: process.env.SOLEDGIC_API_KEY, allowWrites: true }),
  maxSteps: 5,
  prompt: 'Check if creator_maya is eligible for a payout and request one if she is.',
})
```

The model will automatically call `checkPayoutEligibility` and then
`requestPayout` in sequence — no manual orchestration needed.

## Guardrails (safe by default)

This package follows least privilege. The model only sees the tools you enable:

| Config | Default | Effect |
| --- | --- | --- |
| `allowWrites` | `false` | When false, **only read tools are exposed** (`checkPayoutEligibility`, `listWallets`, `listWalletActivity`, `getApiStatus`). The model cannot move money or mutate state. Set `true` to expose the write tools. |
| `allowLivePayouts` | `false` | Even with `allowWrites: true`, `requestPayout` is blocked on a live key (`slk_live_*`) unless this is `true`. |
| `maxPayoutAmountCents` | `5_000_000` ($50k) | `requestPayout` rejects amounts above this before calling the API. `0` disables the ceiling. |
| `maxCheckoutAmountCents` | `10_000_000` ($100k) | `createCheckoutSession` rejects amounts above this. `0` disables the ceiling. |
| `requireWriteConfirmation` | `true` | High-impact money tools require a per-call confirmation phrase (`CONFIRM_CREATE_CHECKOUT_SESSION` or `CONFIRM_REQUEST_PAYOUT`) before the API is called. Disable only behind your own human approval gate. |

```ts
const tools = soledgicTools({
  apiKey: process.env.SOLEDGIC_API_KEY,
  allowWrites: true,        // expose mutating tools
  allowLivePayouts: true,   // permit ACH payouts on a live key
  maxPayoutAmountCents: 2_000_000, // cap single payout at $20k
  requireWriteConfirmation: true,
})
```

Blocked calls return a structured `{ error, hint }` to the model rather than
throwing, so the agent can explain the limit instead of crashing the run.

## Available tools

Read tools are always available. Write tools (marked ✍️) are only exposed when
`allowWrites: true`.

| Tool | Write | Description |
| --- | :---: | --- |
| `checkPayoutEligibility` | | Check if a creator can receive a payout right now |
| `listWallets` | | List wallet balances for a creator or user |
| `listWalletActivity` | | List recent ledger entries for a wallet |
| `getApiStatus` | | Check API health and verify the API key |
| `createParticipant` | ✍️ | Create or update a creator account (idempotent) |
| `createCheckoutSession` | ✍️ | Create a hosted payment page (bounded by `maxCheckoutAmountCents`) |
| `requestPayout` | ✍️ | Initiate an ACH payout (bounded by `maxPayoutAmountCents`; live needs `allowLivePayouts`) |
| `createRefundRequest` | ✍️ | Create a buyer-facing refund request |
| `completeSandboxCheckout` | ✍️ | Complete a sandbox checkout (test keys only) |

`createCheckoutSession` requires `confirm: "CONFIRM_CREATE_CHECKOUT_SESSION"`
on the tool call. `requestPayout` requires
`confirm: "CONFIRM_REQUEST_PAYOUT"`.

## Example: full marketplace flow

```ts
import { generateText } from 'ai'
import { anthropic } from '@ai-sdk/anthropic'
import { soledgicTools } from '@soledgic/ai/vercel'

const tools = soledgicTools({ apiKey: process.env.SOLEDGIC_API_KEY, allowWrites: true })

// Onboard a creator and create a checkout in one agent call
const { text } = await generateText({
  model: anthropic('claude-sonnet-4-6'),
  tools,
  maxSteps: 10,
  prompt: `
    Onboard a creator with ID "creator_maya", name "Maya Chen", email "maya@example.com",
    and a 90% revenue split. Then create a $50 checkout session for a product called
    "UX Course" with success URL https://example.com/success.
    Return the checkout URL.
  `,
})

console.log(text) // → "Here is the checkout URL: https://soledgic.com/pay/..."
```

## Idempotency

- `createParticipant` — idempotent by `externalCreatorId`
- `requestPayout` — pass a stable `referenceId`; same value on retry won't duplicate
- `createRefundRequest` — pass a stable `idempotencyKey`
- `completeSandboxCheckout` — pass a stable `idempotencyKey`

Never generate a new ID on retry. Use the same one from the original call.

## Sandbox

Use test keys (`slk_test_*`) for development. `completeSandboxCheckout` simulates
a successful payment without contacting a real processor — use it to test your
full agent flow end to end.

```ts
const tools = soledgicTools({ apiKey: 'slk_test_your_key', allowWrites: true })
```

Get a free test key at [soledgic.com/signup](https://soledgic.com/signup).

## Security

This package makes HTTPS requests to `api.soledgic.com` only when a tool is
invoked. It does not perform background calls, telemetry, or analytics.

Never expose your API key to the browser. Always call these tools from a
server-side environment.