# 📦 SDK + Examples

The Saturation SDK offers a TypeScript-native interface to the Saturation API.
It simplifies the process of building applications, dashboards, and AI agents on top of project-based financial workflows.

This page showcases **three experimental sample applications** built with the SDK.
They are ordered from the simplest to the most advanced: **Basic Usage**, **Basic Dashboard**, and **Chatbot Agent**.

> ⚠️ **Note**: These examples are experimental and may change frequently as our SDK evolves.
You can use them to **test your own API key** and explore how the SDK works in practice.


## About the Saturation SDK

The [Saturation SDK](https://github.com/Saturation-IO/saturation-js) provides a developer-friendly way to interact with the Saturation API. It abstracts away raw HTTP requests and gives you:

- Strongly-typed client methods for listing projects, budgets, actuals, and purchase orders
- Secure, ergonomic configuration using environment variables
- A foundation for building dashboards, integrations, and AI tools on top of financial workflows


## 1. Basic Usage App

An introductory Next.js application that lets you experiment with the Saturation API.
This app allows you to **play with what’s returned from the API** and fetch information across **all supported domains** (projects, budgets, contacts, transactions, rates, etc.).

- [Live Demo](https://basic-usage.vercel.app/)
- [Source Code](https://github.com/Saturation-IO/saturation-js/tree/main/examples/basic-usage)


**What you’ll learn:**

- Configuring and initializing the SDK client
- Authenticating with your API key
- Viewing lists of projects, budgets, contacts, rates, and more
- Interacting with API data directly from the browser


**Prerequisites:**

- Node.js v18+
- A Saturation API key (from [Settings](https://app.saturation.io/settings/api-keys))
- Familiarity with TypeScript + Next.js


## 2. Basic Dashboard

A lightweight dashboard that calculates KPIs and displays financial data in charts and tables.

- [Live Demo](https://basic-dashboard-woad.vercel.app/)
- [Source Code](https://github.com/Saturation-IO/saturation-js/tree/main/examples/basic-dashboard)


**What you’ll learn:**

- Calculating KPIs: total budget, actuals, open commitments, remaining, burn %
- Transforming raw API responses into UI-ready data
- Rendering charts using Recharts + `shadcn/ui`
- Structuring a clean, developer-friendly dashboard


**Prerequisites:**

- Node.js v18+
- Saturation API key
- Familiarity with React + charting libraries


## 3. Chatbot Agent

An experimental chatbot that integrates the Saturation SDK with [AI SDK v5](https://ai-sdk.dev/).
This shows how to embed financial tools into a conversational AI flow.

- [Live Demo](https://chatbot-agent-three.vercel.app/)
- [Source Code](https://github.com/Saturation-IO/saturation-js/tree/main/examples/chatbot-agent)


**What you’ll learn:**

- How to integrate Saturation calls into an AI agent runtime
- Invoking methods like `listProjects` through tool calls
- Extending agent capabilities with custom tools
- Designing UIs around interactive AI workflows


**Prerequisites:**

- Node.js v18+
- Saturation API key
- Familiarity with AI agent frameworks


## More Examples

Browse all examples in the [SDK repository](https://github.com/Saturation-IO/saturation-js/tree/main/examples).
They are living demos, designed for testing with your API key and updated regularly as the SDK evolves.