# 🚀 fh-saas


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## ⚡ Quick Start

### 1. Install

``` bash
pip install fh-saas
```

### 2. Configure Environment

``` bash
# .env file
DB_TYPE=POSTGRESQL
DB_USER=postgres
DB_PASS=your_password
DB_HOST=localhost
DB_NAME=app_host

# Optional integrations
STRIPE_SECRET_KEY=sk_...
RESEND_API_KEY=re_...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
```

### 3. Initialize Your App

``` python
from fh_saas.db_host import HostDatabase, GlobalUser, TenantCatalog, Membership, gen_id, timestamp
from fh_saas.db_tenant import get_or_create_tenant_db
from fh_saas.utils_db import register_tables, create_indexes
from fh_saas.utils_log import configure_logging

# Configure logging (once at startup)
configure_logging()

# Connect to host database
host_db = HostDatabase.from_env()

# Create a new user
user = GlobalUser(
    id=gen_id(),
    email="founder@startup.com",
    oauth_id="google_abc123",
    created_at=timestamp()
)
host_db.global_users.insert(user)

# Create a tenant for their organization
tenant = TenantCatalog(
    id=gen_id(),
    name="Acme Corp",
    db_url="postgresql://...",
    created_at=timestamp()
)
host_db.tenant_catalogs.insert(tenant)

# Link user to tenant as owner
membership = Membership(
    id=gen_id(),
    user_id=user.id,
    tenant_id=tenant.id,
    profile_id=gen_id(),
    role="owner",
    created_at=timestamp()
)
host_db.memberships.insert(membership)
host_db.commit()
```

### 4. Work with Tenant Data

``` python
# Get tenant's isolated database
tenant_db = get_or_create_tenant_db(tenant.id, tenant.name)

# Define your app's data models
class Project:
    id: str
    name: str
    status: str = "active"
    created_at: str

class Task:
    id: str
    project_id: str
    title: str
    completed: bool = False

# Register tables (creates if not exist)
tables = register_tables(tenant_db, [
    (Project, "projects", "id"),
    (Task, "tasks", "id"),
])

# Add indexes for performance
create_indexes(tenant_db, [
    ("tasks", ["project_id"], False, None),
    ("tasks", ["completed"], False, None),
])

# Use the tables
projects = tables["projects"]
projects.insert(Project(id=gen_id(), name="Launch MVP", created_at=timestamp()))
tenant_db.conn.commit()
```

------------------------------------------------------------------------

## 📚 Documentation Guide

|  |  |
|----|----|
| Section | What You'll Learn |
| **📦 Core** |  |
| [Multi-Tenant Setup](https://abhisheksreesaila.github.io/fh-saas/db_host.html) | Host database, user management, tenant registry |
| [Tenant Databases](https://abhisheksreesaila.github.io/fh-saas/db_tenant.html) | Isolated databases per tenant, connection pooling |
| [Table Management](https://abhisheksreesaila.github.io/fh-saas/utils_db.html) | Create tables & indexes from dataclasses |
| **🔌 Integrations** |  |
| [HTTP Client](https://abhisheksreesaila.github.io/fh-saas/utils_api.html) | REST APIs with retries, rate limiting, auth |
| [GraphQL Client](https://abhisheksreesaila.github.io/fh-saas/utils_graphql.html) | Streaming pagination for large datasets |
| [Webhooks](https://abhisheksreesaila.github.io/fh-saas/utils_webhook.html) | Receive & verify external webhooks |
| **⚙️ Data Pipeline** |  |
| [Background Tasks](https://abhisheksreesaila.github.io/fh-saas/utils_bgtsk.html) | Async job execution |
| [Data Transforms](https://abhisheksreesaila.github.io/fh-saas/utils_polars_mapper.html) | JSON → Polars → Database pipeline |
| **🛠️ Utilities** |  |
| [SQL Helpers](https://abhisheksreesaila.github.io/fh-saas/utils_sql.html) | Database type detection, query builders |
| [Logging](https://abhisheksreesaila.github.io/fh-saas/utils_log.html) | Configurable logging for all modules |
| [Authentication](https://abhisheksreesaila.github.io/fh-saas/utils_oauth.html) | OAuth flows (Google, GitHub) |
| [Email Sending](https://abhisheksreesaila.github.io/fh-saas/utils_email.html) | Transactional emails via Resend |
| **📣 Content** |  |
| [Blog Publishing](https://abhisheksreesaila.github.io/fh-saas/utils_blog.html) | Markdown blog with frontmatter |
| [SEO & Sitemaps](https://abhisheksreesaila.github.io/fh-saas/utils_seo.html) | Sitemap generation, meta tags |
| [Workflow Engine](https://abhisheksreesaila.github.io/fh-saas/utils_workflow.html) | Multi-step automation |

------------------------------------------------------------------------

## 🛠️ Developer Guide

This project uses [nbdev](https://nbdev.fast.ai/) for literate
programming. The source of truth is in the `nbs/` notebooks.

### Development Setup

``` bash
# Clone and install in dev mode
git clone https://github.com/abhisheksreesaila/fh-saas.git
cd fh-saas
pip install -e .

# Make changes in nbs/ directory, then compile
nbdev_prepare
```

------------------------------------------------------------------------

## 📦 Installation

``` bash
# From PyPI (recommended)
pip install fh-saas

# From GitHub (latest)
pip install git+https://github.com/abhisheksreesaila/fh-saas.git
```

[GitHub](https://github.com/abhisheksreesaila/fh-saas) ·
[PyPI](https://pypi.org/project/fh-saas/) ·
[Documentation](https://abhisheksreesaila.github.io/fh-saas/)

**🤖 For AI Assistants:** [Download
llms-ctx.txt](https://raw.githubusercontent.com/abhisheksreesaila/fh-saas/main/llms-ctx.txt)
— Complete API documentation for LLMs

------------------------------------------------------------------------

## 🤖 AI Assistant Context

**For AI coding assistants** (GitHub Copilot, Claude, ChatGPT, Cursor,
etc.), download the complete API documentation:

**[📥 Download
llms-ctx.txt](https://raw.githubusercontent.com/abhisheksreesaila/fh-saas/main/llms-ctx.txt)**
— Complete fh-saas documentation in LLM-friendly format

### How to use:

1.  Download the context file
2.  Add to your AI assistant’s instructions/knowledge base  
3.  Get accurate code suggestions for fh-saas APIs

This file contains all module documentation, examples, and API
signatures formatted for optimal LLM understanding.

------------------------------------------------------------------------

## 🤝 Contributing

Contributions are welcome! Please check the [GitHub
repository](https://github.com/abhisheksreesaila/fh-saas) for issues and
discussions.

## 🤖 AI Assistant Context

**For AI coding assistants** (GitHub Copilot, Claude, ChatGPT, Cursor,
etc.), download the complete API documentation:

### [📥 Download llms-ctx.txt](https://raw.githubusercontent.com/abhisheksreesaila/fh-saas/main/llms-ctx.txt)

**What’s included:** - Complete module documentation and API
signatures - Code examples and usage patterns - Multi-tenant
architecture patterns - Authentication and security flows - Data
pipeline implementations

**How to use:** 1. Download the `llms-ctx.txt` file 2. Add it to your AI
assistant’s project context or instructions 3. Get accurate,
context-aware code suggestions for fh-saas

This consolidated context file (~500KB) contains all documentation
formatted for optimal LLM understanding, enabling your AI assistant to
provide precise help with fh-saas APIs.
