### Start Development Server

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/quickstart

Launches the Next.js development server, making the application accessible locally. The application typically runs at `http://localhost:3000`.

```bash
npm run dev
```

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

### Navigate to Project Directory

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/quickstart

Changes the current directory to the newly created SaaS Boilerplate project folder, preparing for subsequent setup steps.

```bash
cd my-saas-app
```

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

### Configure Environment Variables

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/quickstart

Copies the example environment file to `.env` and prompts the user to customize it. This file is essential for configuring database connections, API keys, and other environment-specific settings.

```bash
cp .env.example .env
```

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

### Start PostgreSQL with Docker

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/quickstart

Launches the PostgreSQL database service using Docker Compose. This command ensures a local database instance is running for development purposes.

```bash
npm run docker:up
```

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

### Start Stripe Webhook Listener

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/quickstart

Starts a local listener for Stripe webhooks, enabling testing of billing and payment-related events. This is an optional step for features involving Stripe integration.

```bash
npm run stripe:webhook
```

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

### SaaS Boilerplate CLI Configuration Prompts

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/quickstart

Illustrates the interactive prompts presented by the SaaS Boilerplate CLI during project setup. These prompts allow customization of project name, authentication method, package manager, and optional service configurations.

```bash
What is the name of your project? (Required)? my-app
Choose GitHub authentication method (HTTPS or SSH)? https, ssh
Choose your preferred package manager? npm, yarn, pnpm, bun
Do you want to configure Stripe for payments now? No / Yes
Configure Code Agents (LIA) now? No / Yes
Start the development server now? No / Yes
```

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

### Create New Project with SaaS Boilerplate CLI

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/quickstart

Initiates a new SaaS Boilerplate project using the command-line interface. This command automates project creation and guides the user through initial configuration prompts.

```bash
npx saas-boilerplate@latest create my-saas-app
```

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

### Open Prisma Studio

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/quickstart

Opens Prisma Studio, a GUI tool for inspecting and managing your database. This is useful for verifying data and schema after migrations.

```bash
npm run db:studio
```

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

### Install Project Dependencies

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/quickstart

Installs all necessary project dependencies using different package managers (npm, pnpm, yarn). This step is crucial after cloning or creating a new project to ensure all required libraries are available.

```bash
npm install
```

```bash
pnpm install
```

```bash
yarn install
```

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

### Start Email Preview Server (Shell)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/email

Starts a development server for real-time previewing and testing of email templates. This command is typically run during development to iterate on template design and functionality.

```shell
npm run dev:email
```

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

### SEO-Optimized Controllers (Igniter Framework)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/seo

Creates backend controllers within the Igniter framework that support SEO metadata. This example demonstrates a blog controller that fetches a blog post by slug and includes SEO-relevant information in the response. Dependencies include the Igniter framework and a database context.

```typescript
// Blog controller with SEO support
export const blogController = igniter.controller({
  name: 'Blog',
  path: '/blog',
  actions: {
    getBySlug: igniter.query({
      name: 'getBlogPost',
      description: 'Get blog post by slug with SEO metadata',
      method: 'GET',
      path: '/:slug',
      handler: async ({ context, request, response }) => {
        const post = await context.database.blogPost.findUnique({
          where: { slug: request.params.slug },
          include: { author: true, tags: true }
        })
        
        if (!post) {
          return response.notFound({ message: 'Post not found' })
        }
        
        // Add SEO metadata to response
        return response.success(post, {
          seo: {
            title: post.title,
            description: post.excerpt,
            image: post.featuredImage,
            publishedTime: post.publishedAt,
            modifiedTime: post.updatedAt,
            author: post.author.name,
            tags: post.tags.map(tag => tag.name)
          }
        })
      }
    })
  }
})
```

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

### Start MailHog for Local Email Testing

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/email

Provides commands to start MailHog, a local SMTP server for capturing and inspecting emails during development. It includes instructions for Docker and a provided script.

```bash
# Using Docker (recommended)
docker run -d -p 1025:1025 -p 8025:8025 mailhog/mailhog

# Or using the provided script
npm run docker:up
```

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

### Run Database Migrations

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/quickstart

Applies database schema changes to the local PostgreSQL instance using Prisma. This command ensures the database structure is up-to-date with the project's schema definition.

```bash
npm run db:migrate:dev
```

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

### Example MDX Content with Custom Components

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/content-layer

Demonstrates writing content using Markdown and custom JSX components like Steps and Banner. This allows for rich formatting and interactive elements within documentation or blog posts.

```markdown
# My Article Title

This is regular markdown content.

<Steps>
<Step>
### Step 1
Do something important.
</Step>
<Step>
### Step 2  
Do the next thing.
</Step>
</Steps>

<Banner type="info">
Here's a helpful tip!
</Banner>
```

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

### GET /

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/authentication-and-sessions

Retrieves a list of leads for the currently active organization. Requires authentication and an active organization context.

```APIDOC
## GET /

### Description
List all leads for an organization. This endpoint requires the user to be authenticated and have an active organization selected. It enforces role-based access control.

### Method
GET

### Endpoint
/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{} 
```

### Response
#### Success Response (200)
Returns a list of lead objects associated with the active organization.

#### Response Example
```json
{
  "leads": [
    {
      "id": "lead-abc",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "organizationId": "org-xyz"
    }
  ]
}
```

#### Error Response (401)
Returned if the user is not authenticated or an active organization is not set.

```json
{
  "message": "Authentication required and active organization needed."
}
```
```

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

### Frontend: Build Subscription Management UI

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/billing

Provides an example of how to build a billing dashboard on the frontend. It retrieves billing data, displays subscription information such as plan name and status, and shows feature usage against limits.

```javascript
// Get billing data for dashboard
const billing = await api.billing.getSessionCustomer.query()

// Display subscription info
const { subscription, customer, paymentMethods } = billing.data

// Show current plan
console.log(`Plan: ${subscription.plan.name}`)
console.log(`Status: ${subscription.status}`)

// Show usage
subscription.usage.forEach(feature => {
  console.log(`${feature.name}: ${feature.usage}/${feature.limit}`)
})
```

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

### Clone SaaS Boilerplate Repository

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/quickstart

Manually clones the SaaS Boilerplate project from its GitHub repository. This method is suitable for users who prefer direct control over the project files or wish to contribute to the boilerplate.

```bash
git clone https://github.com/felipebarcelospro/saas-boilerplate
cd saas-boilerplate
```

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

### Igniter Client Setup (TypeScript)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/data-fetching

Sets up the Igniter client for type-safe API access, handling context switching between server and client environments. It configures base URLs and paths, and dynamically loads the appropriate router implementation.

```typescript
import { createIgniterClient } from 'igniter.js';

// Assuming AppRouterType is defined elsewhere
// import { AppRouterType } from './igniter.router';

export const api = createIgniterClient<AppRouterType>({
  baseURL: process.env.NEXT_PUBLIC_IGNITER_APP_URL,
  basePATH: process.env.NEXT_PUBLIC_IGNITER_APP_BASE_PATH,
  router: () => {
    if (typeof window === 'undefined') {
      // Server-side: Direct router access (zero HTTP overhead)
      return require('./igniter.router').AppRouter
    }
    // Client-side: HTTP-based client with hooks
    return require('./igniter.schema').AppRouterSchema
  }
})
```

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

### Configure MCP Clients

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/built-in-mcp-server

Examples for configuring external AI clients to connect to the SaaS MCP server via HTTP/SSE.

```json
// .cursor/mcp.json
{
  "mcpServers": {
    "your-saas": {
      "type": "http",
      "url": "https://yourapp.com/mcp/sk_xxx.../sse"
    }
  }
}
```

```json
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "your-saas": {
      "type": "http",
      "url": "https://yourapp.com/mcp/sk_xxx.../sse"
    }
  }
}
```

```json
// .vscode/mcp.json
{
  "servers": {
    "your-saas": {
      "command": "npx",
      "args": ["@vercel/mcp-adapter", "http://localhost:3000/mcp/sk_xxx.../sse"]
    }
  }
}
```

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

### Initialize Payment Service with Stripe

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/billing

Configures the PaymentProvider using Stripe adapters, database integration, and subscription plan definitions. This setup is required to enable billing features.

```typescript
export const payment = PaymentProvider.initialize({
  database: prismaAdapter(prisma),
  adapter: stripeAdapter({
    secretKey: process.env.STRIPE_SECRET_KEY,
    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
  }),
  paths: {
    checkoutCancelUrl: `${baseUrl}/billing/cancel`,
    checkoutSuccessUrl: `${baseUrl}/billing/success`,
    portalReturnUrl: `${baseUrl}/settings/billing`,
  },
  subscriptions: {
    enabled: true,
    trial: { enabled: true, duration: 14 },
    plans: {
      default: 'free',
      options: [
        { slug: 'free', name: 'Free', prices: [...] },
        { slug: 'pro', name: 'Pro', prices: [...] },
      ]
    }
  }
})
```

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

### GET /plan

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/billing

Retrieves a list of available subscription plans configured in the system.

```APIDOC
## GET /plan

### Description
Returns an array of available subscription plans.

### Method
GET

### Endpoint
/plan

### Response
#### Success Response (200)
- **plans** (array) - List of available plan objects.

#### Response Example
[
  { "id": "basic", "price": 10 },
  { "id": "pro", "price": 30 }
]
```

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

### Initialize Storage Service

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/file-storage

Configures the storage provider with an S3-compatible adapter and defined access contexts. This setup is required to enable file operations throughout the application.

```typescript
export const storage = StorageProvider.initialize({
  adapter: CompatibleS3StorageAdapter,
  credentials: AppConfig.providers.storage,
  contexts: ['user', 'organization', 'public'] as const,
})
```

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

### MCP Client Connection Example (JSON)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/built-in-mcp-server

Demonstrates how an AI client, such as Cursor or Claude, connects to your MCP endpoint using an organization-specific API key. This configuration specifies the MCP server type and its URL.

```json
{
  "mcpServers": {
    "your-saas": {
      "type": "http",
      "url": "https://yourapp.com/mcp/sk_xxx.../sse"
    }
  }
}
```

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

### Implement Blog SEO Metadata with Igniter and Next.js

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/seo

This snippet demonstrates how to fetch blog post data with SEO metadata from a backend controller and how to consume that data in a Next.js page to generate dynamic Open Graph and Twitter metadata.

```typescript
// Blog controller with SEO metadata
export const blogController = igniter.controller({
  name: 'Blog',
  path: '/blog',
  actions: {
    getBySlug: igniter.query({
      name: 'getBlogPost',
      description: 'Get blog post with SEO metadata',
      method: 'GET',
      path: '/:slug',
      handler: async ({ context, request, response }) => {
        const post = await context.database.blogPost.findUnique({
          where: { slug: request.params.slug },
          include: { 
            author: { select: { name: true, image: true } },
            tags: { select: { name: true } },
            category: { select: { name: true } }
          }
        })
        
        if (!post) {
          return response.notFound({ message: 'Post not found' })
        }
        
        const seoMetadata = {
          title: post.title,
          description: post.excerpt || post.content.substring(0, 160),
          image: post.featuredImage,
          publishedTime: post.publishedAt,
          modifiedTime: post.updatedAt,
          author: post.author.name,
          tags: post.tags.map(tag => tag.name),
          category: post.category?.name,
          wordCount: post.content.split(' ').length,
          readingTime: Math.ceil(post.content.split(' ').length / 200)
        }
        
        return response.success({
          post,
          seo: seoMetadata
        })
      }
    })
  }
})

// Blog post page
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const result = await api.blog.getBySlug.query({ 
    params: { slug: params.slug } 
  })
  
  if (!result.data) {
    return { title: 'Post Not Found' }
  }
  
  const { post, seo } = result.data
  
  return {
    title: seo.title,
    description: seo.description,
    keywords: seo.tags,
    authors: [{ name: seo.author }],
    openGraph: {
      title: seo.title,
      description: seo.description,
      images: [{ url: seo.image, width: 1200, height: 630, alt: seo.title }],
      type: 'article',
      publishedTime: seo.publishedTime,
      modifiedTime: seo.modifiedTime,
      authors: [seo.author],
      tags: seo.tags,
    },
    twitter: {
      card: 'summary_large_image',
      title: seo.title,
      description: seo.description,
      images: [seo.image],
    }
  }
}
```

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

### Configure Sitemap (Next.js)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/seo

Generates a comprehensive sitemap for a Next.js application, including static and dynamic routes. It fetches dynamic pages from a database and formats them according to the sitemap protocol. Dependencies include Next.js metadata routing and a function to retrieve dynamic page data.

```typescript
// src/app/sitemap.ts
import { MetadataRoute } from 'next'

export default function sitemap(): MetadataRoute.Sitemap {
  const baseUrl = process.env.NEXT_PUBLIC_APP_URL
  
  // Static pages
  const staticPages = [
    { url: '/', priority: 1, changeFrequency: 'weekly' },
    { url: '/pricing', priority: 0.8, changeFrequency: 'monthly' },
    { url: '/blog', priority: 0.7, changeFrequency: 'weekly' },
    { url: '/docs', priority: 0.7, changeFrequency: 'weekly' },
    { url: '/contact', priority: 0.5, changeFrequency: 'yearly' },
  ]
  
  // Dynamic pages (fetch from database)
  const dynamicPages = await getDynamicPages()
  
  return [
    ...staticPages.map(page => ({
      url: `${baseUrl}${page.url}`,
      lastModified: new Date(),
      changeFrequency: page.changeFrequency as any,
      priority: page.priority,
    })),
    ...dynamicPages
  ]
}
```

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

### Backend Product CRUD with Caching (TypeScript)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/data-fetching

Provides a backend example for e-commerce product management using `igniter.controller`. It includes a `list` query with pagination and a `create` mutation that handles authentication, data validation using `zod`, and cache revalidation upon successful creation. This ensures that product lists are updated after new products are added.

```typescript
// Product controller with caching and revalidation
export const productController = igniter.controller({
  name: 'Products',
  path: '/products',
  actions: {
    list: igniter.query({
      name: 'listProducts',
      description: 'Get paginated product list',
      method: 'GET',
      path: '/',
      handler: async ({ context, request, response }) => {
        const { page = 1, limit = 20, category } = request.query
        
        const products = await context.database.product.findMany({
          where: category ? { categoryId: category } : {},
          skip: (page - 1) * limit,
          take: limit,
          include: { category: true }
        })
        
        return response.success({
          products,
          pagination: { page, limit, total: products.length }
        })
      }
    }),
    
    create: igniter.mutation({
      name: 'createProduct',
      description: 'Create new product',
      method: 'POST',
      path: '/',
      use: [AuthFeatureProcedure()],
      body: z.object({
        name: z.string(),
        price: z.number(),
        categoryId: z.string()
      }),
      handler: async ({ context, request, response }) => {
        const session = await context.auth.getSession({
          requirements: 'authenticated',
          roles: ['admin']
        })
        
        const product = await context.database.product.create({
          data: {
            ...request.body,
            organizationId: session.organization.id
          }
        })
        
        // Revalidate product lists
        return response.revalidate(['products.list']).created(product)
      }
    })
  }
})
```

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

### Initialize Help Category Directory

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/content-layer

Uses shell commands to create a new category directory for help articles within the project structure.

```bash
mkdir -p src/content/help/(troubleshooting)
```

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

### Run Database Migrations and Development Server

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/environment-setup

Commands to initialize the database schema using Prisma and launch the Next.js development server. These are essential steps for setting up the local environment after configuring environment variables.

```bash
npm run db:migrate:dev
npm run dev
```

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

### Manage Docker Containers and Migrations

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/first-deploy

Standard commands to initialize the database, apply schema migrations, and manage the lifecycle of Docker containers.

```shell
docker-compose up -d db
npx prisma migrate deploy
docker-compose up -d
docker-compose logs
```

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

### Configure PWA Manifest (Next.js)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/seo

This function defines the manifest for a Progressive Web App (PWA) using Next.js's `MetadataRoute.Manifest` type. It specifies application details like name, short name, description, start URL, display mode, colors, and icons. This configuration is essential for PWA functionality, enabling offline access and installation on user devices.

```typescript
// src/app/manifest.ts
export default function manifest(): MetadataRoute.Manifest {
  return {
    name: 'Your SaaS App',
    short_name: 'SaaS App',
    description: 'A comprehensive SaaS application',
    start_url: '/app',
    display: 'standalone',
    background_color: '#0f0f0f',
    theme_color: '#0f0f0f',
    icons: [
      {
        src: '/icon-192x192.png',
        sizes: '192x192',
        type: 'image/png',
      },
      {
        src: '/icon-512x512.png',
        sizes: '512x512',
        type: 'image/png',
      },
    ],
  }
}
```

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

### GET /leads

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/authentication-and-sessions

Retrieves a list of leads for the currently active organization with role-based access control.

```APIDOC
## GET /

### Description
Lists all leads associated with the user's active organization. Requires authentication and specific role permissions.

### Method
GET

### Endpoint
/

### Parameters
#### Query Parameters
- **None**

### Response
#### Success Response (200)
- **leads** (array) - List of lead objects

#### Response Example
{
  "success": true,
  "data": [ { "id": "1", "name": "Lead Name" } ]
}
```

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

### POST /

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/authentication-and-sessions

Creates a new lead within the user's active organization. Requires authentication and an active organization context.

```APIDOC
## POST /

### Description
Create a new lead. This endpoint allows the creation of a new lead record, scoped to the user's active organization. Authentication and role validation are performed.

### Method
POST

### Endpoint
/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **email** (string) - Required - The email address of the lead.
- **name** (string) - Required - The name of the lead.
- **phone** (string) - Optional - The phone number of the lead.
- **metadata** (object) - Optional - Additional metadata for the lead.

### Request Example
```json
{
  "email": "jane.doe@example.com",
  "name": "Jane Doe",
  "phone": "123-456-7890",
  "metadata": {
    "source": "website"
  }
}
```

### Response
#### Success Response (200)
Returns the newly created lead object.

#### Response Example
```json
{
  "lead": {
    "id": "lead-def",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "organizationId": "org-xyz",
    "createdAt": "2023-10-27T10:00:00Z"
  }
}
```

#### Error Response (401)
Returned if the user is not authenticated or an active organization is not set.

```json
{
  "message": "Authentication required and active organization needed."
}
```
```

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

### GET /notification/unread-count

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/notifications

Retrieves the count of unread notifications.

```APIDOC
## GET /notification/unread-count

### Description
Retrieves the count of unread notifications.

### Method
GET

### Endpoint
/notification/unread-count

### Response
#### Success Response (200)
- **count** (integer) - The number of unread notifications.

#### Response Example
```json
{
  "count": 3
}
```
```

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

### Initialize Storage Provider

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/file-storage

Initializes the storage provider with a specified adapter, credentials, contexts, and a callback for successful uploads. It demonstrates how to set up the S3-compatible storage system.

```typescript
// src/@saas-boilerplate/providers/storage/storage.provider.ts
const storageProvider = StorageProvider.initialize({
  adapter: CompatibleS3StorageAdapter,
  credentials: AppConfig.providers.storage,
  contexts: ['user', 'organization', 'public'] as const,
  onFileUploadSuccess: (file, url) => {
    console.log(`File uploaded: ${file.name} -> ${url}`)
  }
})
```

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

### GET /notification/user-preferences

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/notifications

Retrieves the current user's notification preferences.

```APIDOC
## GET /notification/user-preferences

### Description
Retrieves the current user's notification preferences.

### Method
GET

### Endpoint
/notification/user-preferences

### Response
#### Success Response (200)
- **preferences** (object) - An object containing the user's notification preferences.
  - **types** (array) - A list of notification types the user is subscribed to.

#### Response Example
```json
{
  "preferences": {
    "types": ["email", "push", "sms"]
  }
}
```
```

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

### Deploy MinIO Storage via Docker

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/file-storage

Command to run a MinIO server instance using Docker. Configures access credentials and maps local storage volumes for persistence.

```bash
docker run -d \
  -p 9000:9000 -p 9001:9001 \
  --name minio \
  -e "MINIO_ACCESS_KEY=minioadmin" \
  -e "MINIO_SECRET_KEY=minioadmin" \
  -v ~/minio/data:/data \
  quay.io/minio/minio server /data --console-address ":9001"
```

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

### GET /notification

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/notifications

Retrieves a paginated list of notifications for the current user.

```APIDOC
## GET /notification

### Description
Retrieves a paginated list of notifications for the current user.

### Method
GET

### Endpoint
/notification

### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **limit** (integer) - Optional - The number of notifications per page.

### Response
#### Success Response (200)
- **notifications** (array) - A list of notification objects.
  - **id** (string) - The unique identifier of the notification.
  - **message** (string) - The content of the notification.
  - **read** (boolean) - Indicates if the notification has been read.
  - **createdAt** (string) - The timestamp when the notification was created.

#### Response Example
```json
{
  "notifications": [
    {
      "id": "notif_abc123",
      "message": "Your subscription is about to expire.",
      "read": false,
      "createdAt": "2023-10-27T10:00:00Z"
    }
  ],
  "totalPages": 5,
  "currentPage": 1
}
```
```

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

### Implement Role-Based Access Control for Lead Listing (TypeScript)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/authentication-and-sessions

Demonstrates how to use the authentication context within a query controller to enforce role-based access control. It retrieves the user's session, validates the active organization, and fetches leads based on permissions.

```typescript
list: igniter.query({
  name: 'List',
  description: 'List all leads for an organization.',
  path: '/',
  use: [AuthFeatureProcedure(), LeadProcedure()],
  handler: async ({ context, response }) => {
    const session = await context.auth.getSession({
      requirements: 'authenticated',
      roles: ['admin', 'owner', 'member'],
    })

    if (!session || !session.organization) {
      return response.unauthorized(
        'Authentication required and active organization needed.',
      )
    }

    const organizationId = session.organization.id
    const leads = await context.lead.findMany(organizationId)

    return response.success(leads)
  },
}),
```

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

### MinIO Environment Variables for Local Development

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/file-storage

Sets up environment variables for local development using MinIO. These variables define the connection details for the MinIO instance, including the endpoint, access keys, region, and bucket name.

```bash
# Environment variables
STORAGE_ENDPOINT=http://localhost:9000
STORAGE_ACCESS_KEY_ID=minioadmin
STORAGE_SECRET_ACCESS_KEY=minioadmin
STORAGE_REGION=us-east-1
STORAGE_BUCKET=my-bucket
```

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

### GET /users

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/data-fetching

Retrieves a paginated list of users for the authenticated organization. Requires administrative privileges.

```APIDOC
## GET /users

### Description
Fetches a list of users associated with the authenticated user's organization. This endpoint supports caching for performance.

### Method
GET

### Endpoint
/users/

### Parameters
None

### Response
#### Success Response (200)
- **data** (array) - List of user objects

#### Response Example
{
  "data": [
    {
      "id": "user_123",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "member"
    }
  ]
}
```

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

### GET /billing/subscription

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/billing

Retrieves the current billing and subscription information for the authenticated user or organization.

```APIDOC
## GET /billing/subscription

### Description
Fetches the current subscription status and billing details.

### Method
GET

### Endpoint
/billing/subscription

### Response
#### Success Response (200)
- **billingInfo** (object) - The subscription and billing status object.

#### Response Example
{
  "status": "active",
  "plan": "pro",
  "current_period_end": 1735689600
}
```

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

### GET /analytics/dashboard

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/data-fetching

Retrieves aggregated analytics including user growth, total revenue, and top-performing products for the authenticated organization.

```APIDOC
## GET /analytics/dashboard

### Description
Fetches a dashboard summary containing user statistics, total revenue, and top 5 products based on sales count for the authenticated organization. Data is filtered by a specified time period.

### Method
GET

### Endpoint
/analytics/dashboard

### Parameters
#### Query Parameters
- **period** (string) - Optional - The time range for the analytics (e.g., '30d'). Defaults to '30d'.

### Request Example
GET /analytics/dashboard?period=30d

### Response
#### Success Response (200)
- **users** (array) - Grouped user creation statistics.
- **revenue** (number) - Total revenue sum for the period.
- **topProducts** (array) - List of the top 5 products by sales count.

#### Response Example
{
  "users": [{"createdAt": "2023-10-01", "_count": 10}],
  "revenue": 5000.50,
  "topProducts": [{"id": "prod_1", "name": "Example Product", "salesCount": 100}]
}
```

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

### Initialize Notification Service

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/notifications

Demonstrates how to instantiate the NotificationService with defined delivery channels and notification templates.

```typescript
// src/services/notification.ts
const notification = new NotificationService({
  context: {} as NotificationContext,
  channels: {
    'email': { /* email delivery logic */ },
    'in-app': { /* database storage logic */ }
  },
  templates: {
    USER_INVITED: { /* template definition */ },
    LEAD_CREATED: { /* template definition */ },
    // ... more templates
  }
})
```

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

### Get Unread Notification Count

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/notifications

Retrieve the total count of unread notifications, typically used for displaying badges in the UI.

```javascript
// Get unread count
const { count } = await api.notification.unreadCount.query()

// Update UI badge
updateNotificationBadge(count)
```

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

### POST /sign-in

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/authentication-and-sessions

Initiates an OAuth authentication flow using a specified provider.

```APIDOC
## POST /sign-in

### Description
Initiates the sign-in process using external OAuth providers like GitHub or Google.

### Method
POST

### Endpoint
/sign-in

### Request Body
- **provider** (string) - Required - The OAuth provider name (e.g., 'github', 'google')
- **callbackURL** (string) - Optional - The URL to redirect to after successful authentication

### Request Example
{
  "provider": "github",
  "callbackURL": "/dashboard"
}

### Response
#### Success Response (200)
- **data** (object) - Authentication result data

#### Response Example
{
  "success": true,
  "data": { "token": "..." }
}
```

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

### Integrations Management API

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/plugin-manager

Endpoints for managing integrations, including listing, retrieving, installing, updating, and uninstalling plugins. These are typically managed via a dashboard.

```APIDOC
## Integrations Management API

### Description
Endpoints for managing integrations within the SaaS Boilerplate. These endpoints allow for the installation, configuration, and removal of plugins. Typically accessed via the `/app/integrations` dashboard.

### Endpoints
- **findMany**: List all installed integrations.
- **findOne**: Get details of a specific integration.
- **install**: Install a new plugin.
- **update**: Modify the settings of an existing integration.
- **uninstall**: Remove an integration.
- **setupPluginsForOrganization**: Initialize plugins for a given organization (internal use).

### Method
These endpoints generally use standard REST methods (GET, POST, PUT, DELETE) depending on the operation.
```

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

### Send Notifications from Backend

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/notifications

Provides examples for triggering notifications within backend procedures, including sending to specific recipients or broadcasting to all organization members.

```typescript
// In a procedure or controller
await context.services.notification.send({
  type: 'USER_INVITED',
  data: {
    organizationName: organization.name,
    inviterName: session.user.name,
    role: invitation.role
  },
  context: {
    recipientId: invitation.email, // Send to specific user
    organizationId: organization.id
  }
})

// Notify all organization members
await context.services.notification.send({
  type: 'LEAD_CREATED',
  data: {
    leadName: lead.name,
    leadEmail: lead.email,
    source: 'website'
  },
  context: {
    organizationId: session.organization.id // Notify all members
  }
})
```

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

### POST /sign-in

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/authentication-and-sessions

Initiates the sign-in process with a specified OAuth provider. It handles the redirection and callback logic for various authentication providers.

```APIDOC
## POST /sign-in

### Description
Sign in with OAuth provider. This endpoint initiates the authentication flow with a chosen provider and handles the callback.

### Method
POST

### Endpoint
/sign-in

### Parameters
#### Query Parameters
None

#### Request Body
- **provider** (string) - Required - The OAuth provider to use for sign-in (e.g., 'google', 'github').
- **callbackURL** (string) - Optional - The URL to redirect to after successful authentication.

### Request Example
```json
{
  "provider": "google",
  "callbackURL": "https://your-app.com/auth/callback"
}
```

### Response
#### Success Response (200)
Returns data related to the authentication result, which may include tokens or user information.

#### Response Example
```json
{
  "data": {
    "userId": "user-123",
    "token": "jwt-token-string"
  }
}
```

#### Error Response (400 or 500)
Returns an error code if the sign-in process fails.

```json
{
  "error": {
    "code": "PROVIDER_ERROR"
  }
}
```
```

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

### Initialize Mail Provider with Templates

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/email

Initializes the MailProvider with configuration, including secret, sender address, an adapter, and a map of email templates. This sets up the core email sending functionality.

```typescript
const mailProvider = MailProvider.initialize({
  secret: AppConfig.providers.mail.secret,
  from: AppConfig.providers.mail.from,
  adapter: getAdapter(AppConfig.providers.mail.provider),
  templates: {
    welcome: welcomeEmailTemplate,
    'organization-invite': organizationInviteTemplate,
    // ... more templates
  }
})
```

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

### Verify Database and Stripe Integration

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/getting-started/environment-setup

Utility commands for verifying the database state via Prisma Studio and testing Stripe webhook connectivity locally.

```bash
npm run db:studio
stripe listen --forward-to localhost:3000/api/webhooks/stripe
```

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

### Template Data Validation Example (TypeScript)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/email

Illustrates how template data is validated against a Zod schema defined for the email template. Sending data that does not conform to the schema will result in a validation error.

```typescript
// This will throw if data doesn't match schema
await mail.send({
  template: 'welcome',
  to: 'user@example.com',
  data: {
    name: 'John Doe', // ✅ Valid
    email: 'john@example.com', // ✅ Valid
    invalidField: 'not allowed' // ❌ Would cause validation error
  }
})
```

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

### Send User Registration Welcome Email

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/email

Demonstrates how to trigger a welcome email notification upon successful user registration using the igniter procedure handler.

```typescript
export const registerUser = igniter.procedure({
  handler: async ({ context, request }) => {
    const user = await createUser(request.body)
    
    await notification.send({
      type: 'USER_REGISTERED',
      context: { recipientId: user.id },
      data: {
        userName: user.name,
        email: user.email,
        dashboardUrl: '/app/dashboard'
      }
    })
    
    return response.created(user)
  }
})
```

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

### ISR Configuration for Marketing Pages (TypeScript)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/data-fetching

Configures Incremental Static Regeneration (ISR) for a page by setting the `revalidate` option. This example shows how to fetch data for a documentation page and revalidate it every hour.

```typescript
// src/app/docs/page.tsx
import { api } from '@/igniter.client'; // Assuming api is imported

export const revalidate = 3600 // Revalidate every hour

export default async function DocsPage() {
  const docs = await api.docs.list.query()
  return <DocsContent docs={docs.data} />
}
```

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

### Backend: Send Lead Creation Notification

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/notifications

In the backend, after creating a lead, send a notification of type 'LEAD_CREATED' to all organization members. This example demonstrates integrating notification sending within a mutation handler.

```javascript
// In lead creation controller/procedure
export const createLead = igniter.mutation({
  // ... other config
  handler: async ({ context, request, response }) => {
    const session = await context.auth.getSession({
      requirements: 'authenticated'
    })

    // Create the lead
    const lead = await context.database.lead.create({
      data: request.body
    })

    // Send notification to all organization members
    await context.services.notification.send({
      type: 'LEAD_CREATED',
      data: {
        leadName: lead.name,
        leadEmail: lead.email,
        source: 'website'
      },
      context: {
        organizationId: session.organization.id
      }
    })

    return response.created(lead)
  }
})
```

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

### Expose Data as MCP Resources with .addResource()

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/built-in-mcp-server

Shows how to expose application data, such as policies or documentation, as accessible resources for AI models. It uses URI schemes and mime types to define how content is served.

```typescript
export const McpServer = (organizationId: string) => {
  return IgniterMCPServer.create()
    .router(igniter.router({ controllers: { /* ... */ } }))
    .addResource({
      uri: `org://${organizationId}/company-policy`,
      name: 'Company Policy',
      description: 'Current company policies and guidelines',
      mimeType: 'text/markdown',
      handler: async () => {
        const policy = await getCompanyPolicy(organizationId)
        return { text: policy }
      }
    })
    .addResource({
      uri: `org://${organizationId}/user-guide`,
      name: 'User Guide',
      description: 'Application user guide and documentation',
      mimeType: 'text/html',
      handler: async () => {
        const guide = await generateUserGuide(organizationId)
        return { text: guide }
      }
    })
    .build()
}
```

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

### Sitemap Generation (Next.js)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/seo

Automatically generates an XML sitemap for the application, crucial for search engine crawlers to discover and index content. It includes URL, last modified date, change frequency, and priority.

```typescript
// src/app/sitemap.ts
export default function sitemap(): MetadataRoute.Sitemap {
  return [
    {
      url: `${base}/`,
      lastModified: now,
      changeFrequency: 'weekly',
      priority: 1,
    },
    // ... more entries
  ]
}
```

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

### Manage API Keys (TypeScript)

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/api-keys

Provides examples for retrieving, updating, and deleting API keys associated with an organization. Ensure `ApiKeyFeatureProcedure` is included in the controller's `use` array to access the necessary context methods.

```typescript
// In a controller with ApiKeyFeatureProcedure in use array
const apiKeys = await context.apikey.findManyByOrganization(orgId)

// Update key status
await context.apikey.update({
  id: 'key_123',
  description: 'Updated description',
  enabled: false
})

// Delete a key
await context.apikey.delete({
  id: 'key_123',
  organizationId: orgId
})
```

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

### Define MCP Prompts with .addPrompt()

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/built-in-mcp-server

Demonstrates how to register a structured prompt template in an MCP server. This allows for consistent AI interaction patterns by defining schemas and message handlers.

```typescript
export const McpServer = (organizationId: string) => {
  return IgniterMCPServer.create()
    .router(igniter.router({ controllers: { /* ... */ } }))
    .addPrompt({
      name: 'customer_support',
      description: 'Guide for handling customer support inquiries',
      schema: {
        userId: z.string(),
        timeframe: z.enum(['week', 'month', 'year'])
      },
      handler: async (args, context) => {
        return {
          messages: [
            {
              role: 'user',
              content: {
                type: 'text',
                text: `Please help with this ${args.issue_type} issue. Use the available tools to investigate and resolve.`
              }
            }
          ]
        }
      }
    })
    .build()
}
```

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

### Create MDX Documentation Article

Source: https://demo.saas-boilerplate.vibedev.com.br/docs/development/content-layer

Demonstrates the structure of an MDX file including frontmatter metadata and the use of custom Accordion components for content organization.

```mdx
---
title: "Common Issues & Solutions"
description: "Fix the most frequently encountered problems"
---

# Common Issues & Solutions

<Accordions type="multiple">
<Accordion title="Login problems">
Check your email for the verification link. If you don't see it, check your spam folder.
</Accordion>

<Accordion title="Slow loading">
Clear your browser cache or try a different browser. Contact support if the issue persists.
</Accordion>
</Accordions>
```