AiFredo SDK

Embed AiFredo agents into your own applications — no AiFredo UI, full control over branding and data.

Target customers: Businesses and developers who need white-label AI agents, data control for regulated industries, or deep integration into their own CRM, app, or internal tools.

Installation

npm install @aifredo/sdk

Lock to a specific version for production: npm install @aifredo/[email protected]

Quick Start

import { AiFredo } from '@aifredo/sdk'

const fredo = new AiFredo({
  apiKey: 'your-api-key',
  baseUrl: 'https://aifredo.chat',  // optional, for self-hosted
})

const reply = await fredo.send('fredo-sdr', 'List my prospects')
console.log(reply)

Creating your agent

The SDK talks to agents — it doesn't create them. Create your agent on the platform first:

1. Hosted: Go to aifredo.chat → create or pick an agent
2. Self-hosted: Deploy the platform on your infrastructure, create agents there
3. Use the SDK with your agent's botId — same API either way

You can use existing agents (e.g. fredo-sdr) to try the SDK, or create your own and integrate it into your app.

When do I pay?

• SDK: Free and open source (MIT). Download and use it — no payment for the library itself.
• Platform usage: Payment is for usage of hosted aifredo.chat (messages, API keys, private bots). Free tier: 5 messages per IP; add funds or subscribe for more.
• Self-hosted: Run the platform on your own infra — no usage fees. Enterprise self-hosted may require a license (see pricing).

API Key

Get your key at aifredo.chat/settings/keys. Required for private bots; omit for public bots (5 free messages per IP).

Security

Never expose API keys in client-side code. Use environment variables (process.env.AIFREDO_API_KEY) on the backend. See SECURITY.md for guidance on key storage, widget embedding, and self-hosted deployment.

API Reference

new AiFredo({ apiKey, baseUrl?, debug? })

• apiKey (optional): API key for private bots. Use env vars on backend; never expose in client code.
• baseUrl (optional): Base URL of the AiFredo API. Default: https://aifredo.chat
• debug (optional): Set true to log requests (URL, status) to console for troubleshooting

fredo.send(botId, message, sessionId?)

Sends a message to an agent and returns the reply.

• botId: Agent ID (e.g. fredo-sdr, your-bot-slug)
• message: User message text
• sessionId (optional): Session ID for conversation continuity

Returns: { reply: string, messagesUsed?: number, freeRemaining?: number, limitReached?: boolean }

Throws: LimitReachedError when free limit is exceeded and no paid balance

fredo.stream(botId, message, onChunk, sessionId?)

Streams the reply incrementally for a typing effect.

• botId: Agent ID
• message: User message text
• onChunk: Callback (text: string) => void for each text chunk
• sessionId (optional): Session ID for conversation continuity

Returns: Promise<SendResponse> when stream completes

fredo.health()

Health check for uptime monitoring. Calls GET {baseUrl}/health. Returns { ok: true } on success. Throws on 5xx or network failure.

fredo.status(botId)

Checks message usage and limits for the current session.

Returns: { messagesUsed, freeLimit, freeRemaining, isPaying, balance_cents? }

Self-Hosted

Point the SDK at your own AiFredo instance:

const fredo = new AiFredo({
  apiKey: 'your-key',
  baseUrl: 'https://your-aifredo-instance.com',
})

See SELF_HOSTING.md for details and widget setup. CONFIGURATION.md documents the full config schema. DEPLOYMENT.md covers Docker env injection for self-hosted docs.

Examples

# Node: quick start (send)
node examples/quickstart.js

# Node: streaming
node examples/stream.js

# Node: error handling (LimitReachedError, etc.)
node examples/error-handling.js

# Python (no SDK — raw API)
python examples/python_example.py

# curl
./examples/curl.sh

Set AIFREDO_API_KEY for private bots. AIFREDO_BOT_ID defaults to fredo-sdr.

Widget (no npm): Add a chat bubble to any site with one script tag. See examples/browser-widget.html.

Troubleshooting

| Issue | Fix | |-------|-----| | Bot not found | Check botId — use slug (e.g. fredo-sdr) or bot ID from dashboard | | This agent is private | Add apiKey and ensure your key has access to the bot | | LimitReachedError | Free limit (5 msg) exceeded — sign up and add funds, or use API key with balance | | fetch failed / CORS | Use API key (avoids cookie/session). For browser, ensure baseUrl allows your origin | | Self-hosted 404 | Verify platform is running, SPA fallback is configured (see SELF_HOSTING.md) |

License

MIT

Links

• Get SDK — Install & run guide (GitHub Pages)
• AiFredo Platform
• Platform Docs
• GitHub
• npm
• Pipe Labs LLC