# Igniter.js - Complete Documentation

The first AI-native TypeScript framework — architected for human-AI collaboration. Feature-sliced modules, deep TypeScript inference, and built-in training for 15+ Code Agents (Cursor, Claude Code, Copilot) create a low-entropy environment where both developers and AI work seamlessly. MCP-native APIs, AI agent orchestration, type-safe RPC, background jobs, multi-platform bots, and framework-agnostic runtime support — built for the next era of development.

---


# Blog

Articles, tutorials, and announcements from the Igniter.js team

---

# Announcing Igniter.js MCP Server: Native AI Integration for Modern Development

> Transform your AI coding tools into framework experts with Igniter.js's MCP Server integration. Get instant project understanding, intelligent code generation, and specialized AI assistance built directly into Cursor, Claude Code, and more.
URL: https://igniterjs.com/blog/announcing-igniter-mcp-server

As AI-native development tools reshape how we build software, understanding project context and maintaining architectural consistency has become the new bottleneck. With **Igniter.js MCP Server**, your AI coding assistants can now deeply understand your project structure, execute development commands, and provide intelligent assistance that goes far beyond basic code completion.

## The Evolution of AI-Assisted Development

The rise of AI-native IDEs like Cursor, Windsurf, and Claude Code has enabled developers to write code at unprecedented speeds. But with this velocity comes a new challenge: **AI tools need context to be truly effective**.

Without proper context, even the most advanced AI assistants struggle to:

* Understand your project's architectural patterns
* Follow your specific coding conventions
* Execute project-specific commands correctly
* Maintain consistency across feature implementations

This is where the **Model Context Protocol (MCP)** becomes transformative.

## What is MCP and Why Does It Matter?

The [Model Context Protocol](https://modelcontextprotocol.io/introduction) is an open standard that enables Large Language Models to interact with external systems in a structured, type-safe manner. Think of it as a universal API that AI tools can use to:

* Access your project's file structure and codebase
* Execute development tasks and build commands
* Query project-specific information
* Leverage specialized tools designed for your framework

For Igniter.js, this means your AI assistant becomes a framework expert that understands not just TypeScript, but the specific patterns, conventions, and architecture of your Igniter.js application.

## Getting Started: Install in Under 2 Minutes

Every Igniter.js starter template (v1.0.0+) comes with MCP Server support out of the box. Integration is as simple as adding a configuration file to your AI tool.

<Callout type="success" title="Universal Compatibility">
  The Igniter.js MCP Server works with **any** AI coding tool that supports the Model Context Protocol, including Cursor, Windsurf, Claude Code, Claude Desktop, and VS Code Copilot.
</Callout>

### Quick Installation

<Tabs items={['Cursor', 'Claude Code', 'VS Code Copilot', 'Windsurf']} groupId="ai-tool">
  <Tab value="Cursor">
    Create or edit `~/.cursor/mcp.json`:

    ```json
    {
      "mcpServers": {
        "Igniter": {
          "command": "npx",
          "args": ["@igniter-js/mcp-server"]
        }
      }
    }
    ```

    Restart Cursor to activate the MCP Server.
  </Tab>

  <Tab value="Claude Code">
    ```bash
    # Add the Igniter.js MCP Server
    claude mcp add igniter npx @igniter-js/mcp-server

    # Verify installation
    claude mcp list
    ```
  </Tab>

  <Tab value="VS Code Copilot">
    Create `.vscode/mcp.json` in your project root:

    ```json
    {
      "servers": {
        "Igniter": {
          "command": "npx",
          "args": ["@igniter-js/mcp-server"]
        }
      }
    }
    ```
  </Tab>

  <Tab value="Windsurf">
    Create or edit `~/.codeium/windsurf/mcp_config.json`:

    ```json
    {
      "mcpServers": {
        "Igniter": {
          "command": "npx",
          "args": ["@igniter-js/mcp-server"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## What Can the MCP Server Do?

The Igniter.js MCP Server exposes a comprehensive set of tools that transform your AI assistant into a specialized Igniter.js developer:

### Development Workflow Tools

<Steps>
  <Step>
    ### Start Development Servers

    Launch your application with live reloading and automatic client generation.

    ```typescript
    // AI can execute: start the dev server
    // Runs: igniter dev --watch
    ```
  </Step>

  <Step>
    ### Build for Production

    Compile and optimize your application for deployment.

    ```typescript
    // AI can execute: build the project
    // Runs: igniter build
    ```
  </Step>

  <Step>
    ### Run Test Suites

    Execute comprehensive tests with filtering and watch options.

    ```typescript
    // AI can execute: run tests for the auth feature
    // Runs: npm test -- --filter auth
    ```
  </Step>
</Steps>

### Code Analysis and Generation

* **Analyze Code Structure**: Identify architectural patterns and potential issues
* **Generate Type-Safe Clients**: Auto-generate fully typed API clients from your router
* **Create OpenAPI Documentation**: Generate interactive API documentation with Scalar UI
* **Scaffold Features**: Create complete feature modules from your Prisma schema

### AI-Powered Task Management

The MCP Server integrates with specialized AI agents (Claude, Gemini, GPT, Perplexity) to handle complex development tasks:

```typescript
// Ask your AI: "Create a new authentication feature with JWT tokens"
// The AI delegates to specialized agents who:
// 1. Analyze your current architecture
// 2. Generate the auth controller and procedures
// 3. Create database migrations
// 4. Write comprehensive tests
// 5. Update documentation
```

## Meet Lia: Your AI Framework Specialist

When you use an Igniter.js starter template, you're not just getting a codebase—you're getting **Lia**, a specialized AI agent trained specifically for Igniter.js development.

### How Lia Transforms Your AI Assistant

<Callout type="info" title="Before and After">
  **Before MCP Integration:**
  Your AI: "I see you have a Next.js project. Let me try to understand the structure..."

  **After MCP Integration:**
  Lia-Enhanced AI: "I can see this is an Igniter.js project with feature-based architecture. Your auth module is in `src/features/auth/`. I'll use the `generateController` tool to add the new endpoint following your established patterns."
</Callout>

### Lia's Capabilities

**Contextual Understanding**: Every action starts with comprehensive analysis of your project structure, conventions, and existing patterns.

**Tool Prioritization**: Instead of generic approaches, Lia automatically uses specialized Igniter.js tools for maximum accuracy and efficiency.

**Pattern Replication**: Learns from your existing code to maintain consistency across your entire application.

**Persistent Memory**: Stores architectural decisions and patterns, making future development faster and more consistent.

## Real-World Development Workflow

Here's a typical conversation with a Lia-enhanced AI assistant:

<Steps>
  <Step>
    ### You Ask for a Feature

    **You:** "Add user profile management to the auth feature"
  </Step>

  <Step>
    ### Lia Analyzes Context

    **AI:** "I'll analyze the current auth feature structure..."

    *Automatically runs analysis on the auth directory*
  </Step>

  <Step>
    ### Intelligent Implementation

    **AI:** "I can see you have a `user` controller with basic CRUD. I'll scaffold a `profile` controller following your patterns with Zod validation and the `ensure` plugin."

    *Uses `generateController` tool*
  </Step>

  <Step>
    ### Testing and Validation

    **AI:** "Now I'll test the implementation to ensure it integrates correctly..."

    *Runs validation using MCP Server tools*
  </Step>

  <Step>
    ### Knowledge Persistence

    **AI:** "Implementation complete! I've stored these patterns for future reference."
  </Step>
</Steps>

## Why This Matters for Your Workflow

### Before Igniter.js MCP Server

❌ AI guesses at project structure\
❌ Manual context switching between tools\
❌ Inconsistent code patterns\
❌ Repeated explanations of architecture\
❌ Generic solutions that don't fit your app

### After Igniter.js MCP Server

✅ AI deeply understands your project\
✅ Seamless tool integration\
✅ Consistent, pattern-aware code\
✅ Persistent architectural knowledge\
✅ Framework-specific, optimized solutions

## Advanced: Custom Rules for Maximum Productivity

Every Igniter.js starter includes custom rules that transform your AI assistant's behavior. These rules create a specialized development environment where:

* **File operations start with analysis** to understand context before making changes
* **Specialized tools are prioritized** over generic approaches
* **Architectural patterns are maintained** automatically across features
* **Development workflows are optimized** for Igniter.js best practices

<Callout type="tip" title="Continuous Learning">
  The more you work with Lia-enhanced AI, the smarter it becomes. Every decision, pattern, and insight is stored, creating a continuously improving development assistant that understands your specific project better than any generic AI could.
</Callout>

## Start Building with AI-Native Development

Ready to experience the future of collaborative coding? Choose from our collection of official starter templates, each pre-configured with MCP Server support:

<Steps>
  <Step>
    ### Choose Your Stack

    Select from Next.js, TanStack Start, Bun, Express, or Deno starters
  </Step>

  <Step>
    ### Install MCP Server

    Add the configuration to your preferred AI tool (see tabs above)
  </Step>

  <Step>
    ### Start Conversing

    Begin with simple questions like:

    * "What's the current health status of my project?"
    * "Show me all API endpoints"
    * "Analyze the auth feature for potential issues"
  </Step>
</Steps>

## Integration Examples

### Creating a Complete Feature

```typescript
// You: "Create a posts feature with CRUD operations and real-time updates"

// Lia-enhanced AI automatically:
// 1. Analyzes your Prisma schema
// 2. Generates controller with type-safe actions
// 3. Creates validation schemas with Zod
// 4. Implements real-time SSE streaming
// 5. Generates API client with React hooks
// 6. Writes comprehensive tests
// 7. Updates documentation
```

### Debugging with Context

```typescript
// You: "Why is the user creation endpoint failing?"

// Lia-enhanced AI:
// 1. Analyzes the user controller
// 2. Checks validation schemas
// 3. Reviews database schema
// 4. Examines recent error logs
// 5. Identifies the issue: missing required field
// 6. Proposes and implements the fix
// 7. Runs tests to verify the solution
```

## Community and Next Steps

We're building the future of AI-native development, and we'd love to hear your experience!

* **Share Your Projects**: What are you building with Igniter.js and AI? Let us know on [Twitter](https://twitter.com/igniterjs)
* **Join the Discussion**: Connect with other developers in our [Discord community](https://discord.gg/igniterjs)
* **Contribute**: Help improve the MCP Server on [GitHub](https://github.com/felipebarcelospro/igniter-js)

## Resources

* [MCP Server Documentation](/docs/mcp-server)
* [Custom Rules Guide](/docs/ai-integration/custom-rules)
* [Starter Templates](/templates)
* [GitHub Repository](https://github.com/felipebarcelospro/igniter-js)

***

The world's most AI-native framework is ready for you. Start building smarter, faster, and with unprecedented collaboration between you and your AI coding assistant.


---

# Introducing Igniter.js v1: A Type-Safe TypeScript Framework, Built by AI Agents for AI Agents

> After 1.5 years of development, 4,000+ tests, and 13 production-ready packages — Igniter.js v1 is here. A fully type-safe TypeScript framework designed so AI coding agents produce consistent, scalable, and secure code from day one.
URL: https://igniterjs.com/blog/igniterjs-v1-launch

## Two Years Ago, I Saw the Problem Coming

It was late 2024. My developer community — 11,000+ subscribers of Vibe Dev — was hitting the same wall over and over. AI coding tools like Cursor and Copilot were getting shockingly good at generating code. But every agent built differently. One used Next.js with tRPC. Another spun up Express with handwritten routes. A third produced a NestJS monolith with half the types missing.

The result? Projects that worked on day one fell apart by week three. No consistency. No guardrails. No shared DNA between what one agent built and another maintained.

I asked myself: *what if, instead of forcing AI agents to learn yet another framework, I built a framework designed for them from the ground up?*

Igniter.js was born as a human-AI collaboration experiment. For 1.5 years, I worked alongside AI agents — the same ones my community was struggling with — to build a production-grade TypeScript framework. Every line of code, every architectural decision, every adapter was shaped by both human judgment and agent feedback. The framework was built *by* agents, *for* agents.

Today, I'm shipping v1.

## The Philosophy: Four Principles That Drive Every Decision

Igniter.js isn't just another framework. It's a bet on where software development is heading — a world where humans and AI build together, and the code needs to work for both.

**100% Type Safety, Zero Compromises.** When an AI agent generates code, types aren't a nice-to-have — they're the difference between a function that compiles and one that crashes at runtime. Every Igniter.js package exports fully typed APIs. No `any`. No escape hatches. No "trust me, it works."

**AGENTS.md in Every Package.** Documentation isn't an afterthought here. Every package ships an `AGENTS.md` file that AI coding tools can read directly from `node_modules`. An agent doesn't need to guess the API — it reads the file and knows exactly how to use `IgniterStore`, `IgniterJobs`, or `IgniterAgent` immediately. This is documentation as a first-class API for AI.

**Adapter Architecture — No Vendor Lock-In.** Swap Redis for SQLite. Exchange Express for Bun. Trade Discord for Telegram. Every integration point uses an adapter pattern so you're never trapped by yesterday's decisions.

**Built for Real-World Testing.** The framework ships with an MCP Server that AI agents can use to test endpoints, debug issues, and validate behavior directly inside the IDE — before marking any task complete.

## The Ecosystem: 13 Packages, One Coherent Vision

Each library solves a specific pain point in AI-assisted development. Here's the tour.

### @igniter-js/core — The Declarative Builder

Every AI agent builds API routes differently. Core gives you a single, type-safe builder that wires context, telemetry, store, plugins, and configuration into one coherent application shell.

```ts
import { Igniter } from "@igniter-js/core";

const app = Igniter.create()
  .withContext<{ db: Database }>()
  .withConfig({ basePATH: "/api/v1" })
  .withStore(storeManager)
  .withTelemetry(telemetryManager)
  .addPlugin("auth", authPlugin)
  .build();
```

Controllers, queries, and mutations are defined via dedicated factories — `createIgniterController`, `createIgniterQuery`, `createIgniterMutation` — so every route is fully typed from input to response.

### @igniter-js/store — Unified State, Any Backend

AI agents struggle with state management across requests. Store provides a unified Pub/Sub and caching API regardless of storage backend, with type-safe event schemas enforced at compile time.

```ts
import { IgniterStore, IgniterStoreRedisAdapter, IgniterStoreEvents } from "@igniter-js/store";
import { z } from "zod";

const UserEvents = IgniterStoreEvents.create("user")
  .event("created", z.object({ userId: z.string(), email: z.string().email() }))
  .event("deleted", z.object({ userId: z.string() }))
  .build();

const store = IgniterStore.create()
  .withAdapter(IgniterStoreRedisAdapter.create({ redis }))
  .withService("my-api")
  .addEvents(UserEvents)
  .build();

await store.events.publish("user.created", { userId: "abc", email: "dev@igniter.dev" });
```

### @igniter-js/jobs — Async Processing That Doesn't Break Silently

Async processing is where AI-generated code often fails silently. Jobs gives you declarative, typed queue definitions with built-in telemetry, retry logic, and multi-tenant scope isolation.

```ts
import { IgniterJobs } from "@igniter-js/jobs";
import { IgniterJobsBullMQAdapter } from "@igniter-js/jobs/adapters";

const jobs = IgniterJobs.create()
  .withAdapter(IgniterJobsBullMQAdapter.create({ connection }))
  .withContext<{ db: Database }>(async () => ({ db: await getDb() }))
  .job("sendWelcomeEmail", {
    input: z.object({ userId: z.string() }),
    handler: async ({ input, context }) => {
      const user = await context.db.user.findUnique({ where: { id: input.userId } });
      await mailer.send({ to: user.email, template: "welcome" });
    },
  })
  .build();

await jobs.sendWelcomeEmail.dispatch({ userId: "abc" });
```

### @igniter-js/agents — Strongly-Typed AI Agent Framework

Building AI agents requires messy tool definitions. Agents gives you typed tool registration with auto-generated schemas, multi-agent orchestration, MCP integration, and persistent memory — all validated at compile time.

```ts
import { IgniterAgent, IgniterAgentTool, IgniterAgentToolset } from "@igniter-js/agents";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

const searchDocs = IgniterAgentTool.create("searchDocs")
  .withDescription("Search the project documentation")
  .withInput(z.object({ query: z.string() }))
  .withExecute(async ({ query }) => {
    return await docsIndex.search(query);
  })
  .build();

const toolset = IgniterAgentToolset.create("utils")
  .addTool(searchDocs)
  .build();

const agent = IgniterAgent.create("assistant")
  .withModel(openai("gpt-4"))
  .addToolset(toolset)
  .build();

const result = await agent.generate({ chatId: "chat_123", userId: "user_123", context: {} });
```

### @igniter-js/bot — One Command, Multiple Platforms

Building a bot for one platform is easy. For three? It's a nightmare. Bots unifies the API across Telegram, WhatsApp, and Discord with a single builder.

```ts
import { IgniterBot, telegram, discord, memoryStore } from "@igniter-js/bot";

const bot = IgniterBot.create()
  .withHandle("@demo_bot")
  .withSessionStore(memoryStore())
  .addAdapters({
    telegram: telegram({ token: process.env.TELEGRAM_TOKEN! }),
    discord: discord({ token: process.env.DISCORD_TOKEN!, applicationId: process.env.DISCORD_APP_ID! }),
  })
  .addCommand("start", {
    name: "start",
    description: "Greets the user",
    handle: async (ctx) => {
      await ctx.reply("👋 Welcome to Igniter.js!");
    },
  })
  .build();

await bot.start();
```

### @igniter-js/caller — Type-Safe HTTP Client, Schema-Driven

Frontend agents often craft malformed API calls. Caller generates fully-typed clients with built-in caching, retry logic, interceptors, and telemetry — all from schema definitions.

```ts
import { IgniterCaller } from "@igniter-js/caller";

const client = IgniterCaller.create()
  .withBaseUrl("/api")
  .withHeaders({ "Content-Type": "application/json" })
  .build();

const user = await client.get("/users/abc").send(); // Fully typed response
```

### @igniter-js/cli — One Command to Start

```bash
npx create-igniter-app@latest my-app
```

The CLI scaffolds your project with starters for Next.js, Express, Bun, and TanStack Start — plus add-ons for auth, database, bots, jobs, store, telemetry, and more.

### @igniter-js/collections — Declarative Data Access with a Prisma-like API

AI agents write inconsistent data access patterns. Collections gives you a schema-first, typed query layer that treats files (Markdown, JSON) and key-value stores as structured databases.

```ts
import { IgniterCollections, IgniterCollectionModel } from "@igniter-js/collections";
import { NodeFsAdapter } from "@igniter-js/collections/adapters";
import { z } from "zod";

const Posts = IgniterCollectionModel.create("posts")
  .withBasePath("content/posts")
  .withSchema(z.object({ title: z.string(), published: z.boolean(), tags: z.array(z.string()) }))
  .build();

const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .addCollection(Posts)
  .build();

const published = await docs.posts.findMany({ where: { published: true } });
```

### @igniter-js/connectors — OAuth, Webhooks, and Third-Party Integrations

Every SaaS app needs external integrations. Connectors handles OAuth flows, webhook verification, and credential encryption with multi-tenant scope isolation — so agents don't have to reinvent the wheel.

```ts
import { IgniterConnector, IgniterConnectorManager } from "@igniter-js/connectors";

const slack = IgniterConnector.create()
  .withConfig(z.object({ webhookUrl: z.string().url() }))
  .addAction("notify", {
    input: z.object({ message: z.string() }),
    handler: async ({ input, config }) => {
      await fetch(config.webhookUrl, { method: "POST", body: JSON.stringify({ text: input.message }) });
    },
  })
  .build();

const manager = IgniterConnectorManager.create()
  .withDatabase(adapter)
  .addScope("organization", { required: true })
  .addConnector("slack", slack)
  .build();

const scoped = manager.scope("organization", "org_123");
await scoped.connect("slack", { webhookUrl: "https://hooks.slack.com/..." });
await scoped.action("slack", "notify").call({ message: "Deploy complete!" });
```

### @igniter-js/logger — Structured Logging, Enforced

AI agents produce terrible debug logs. Logger wraps Pino with a builder API, typed log levels, and built-in transports (console, file, HTTP) — making logs structured, searchable, and consistent across every Igniter.js package.

```ts
import { IgniterLogger, IgniterLogLevel } from "@igniter-js/logger";

const logger = IgniterLogger.create()
  .withLevel(IgniterLogLevel.INFO)
  .withAppName("my-api")
  .withComponent("auth")
  .build();

logger.info("User signed up", { userId: "abc", plan: "pro" });
```

### @igniter-js/mail — Typed Email Templates with React Email

Email is deceptively complex. Mail gives you a clean, typed API with React-based templates, provider abstraction (Resend, Postmark, SendGrid, SMTP), optional queue delivery, and full telemetry on every send.

```ts
import { IgniterMail } from "@igniter-js/mail";

const mail = IgniterMail.create()
  .withFrom("hello@igniter.dev")
  .withAdapter("resend", process.env.RESEND_API_KEY!)
  .addTemplate("welcome", welcomeTemplate)
  .build();

await mail.send({ to: "dev@igniter.dev", template: "welcome", data: { name: "Felipe" } });
```

### @igniter-js/telemetry — Auto-Instrumented Observability

AI agents rarely add proper observability. Telemetry gives you a typed event registry, session-based context propagation via AsyncLocalStorage, privacy-safe redaction, and 10 transport adapters (Logger, HTTP, OTLP, Sentry, Slack, Discord, Telegram, and more).

```ts
import { IgniterTelemetry, IgniterTelemetryEvents, LoggerTransportAdapter } from "@igniter-js/telemetry";
import { z } from "zod";

const JobsEvents = IgniterTelemetryEvents.namespace("igniter.jobs")
  .event("job.completed", z.object({ "ctx.job.id": z.string(), "ctx.job.duration": z.number() }))
  .build();

const telemetry = IgniterTelemetry.create()
  .withService("my-api")
  .withEnvironment(process.env.NODE_ENV!)
  .addEvents(JobsEvents)
  .addTransport(LoggerTransportAdapter.create({ logger: console }))
  .withRedaction({ denylistKeys: ["password", "secret"] })
  .build();

telemetry.emit("igniter.jobs.job.completed", {
  attributes: { "ctx.job.id": "job_123", "ctx.job.duration": 142 },
});
```

### @igniter-js/mcp-server — AI Agents as First-Class Citizens

Agents need to read docs, test endpoints, and validate code. The MCP Server gives them a direct line to do this inside the IDE, turning Cursor or Claude Code into a framework expert. It exposes tools for CLI automation, API testing, documentation fetching, GitHub management, and more — all over STDIO.

```bash
npx @igniter-js/mcp-server
```

## What Comes Next

v1 is the foundation. Here's what's on the horizon:

* **Templates.** Production-ready starters for every stack — Next.js, Express, Bun, Deno.
* **Deeper AI Integration.** Tighter agent workflows, auto-generated AGENTS.md improvements, and MCP-powered testing loops.
* **Studio v2.** Interactive API playground built on Scalar, already in development.

Igniter.js is open source, MIT licensed, and built in Brazil for developers everywhere. It's the result of 1.5 years of betting that humans and AI can build better software together — not by treating agents as tools, but by treating them as teammates.

[Star the project on GitHub](https://github.com/felipebarcelospro/igniter-js) · [Read the docs](https://igniter.dev) · [Join the community](https://discord.gg/igniter)

***

**Ready to build?**

```bash
npx create-igniter-app@latest my-app
```


---

# Introducing Igniter.js: The Type-Safe Framework for Modern Full-Stack Development

> Discover how Igniter.js eliminates the friction of full-stack development with end-to-end type safety, real-time capabilities, and an exceptional developer experience. Built for the AI-assisted coding era.
URL: https://igniterjs.com/blog/introducing-igniter-js

The modern web development landscape presents a paradox: we have more powerful tools than ever, yet building full-stack applications remains unnecessarily complex. Type safety breaks at API boundaries, state synchronization requires intricate solutions, and backend infrastructure demands expertise in multiple systems.

**Igniter.js** solves these fundamental challenges by treating your entire application as a unified, type-safe system. Created by [Felipe Barcelos](https://github.com/felipebarcelospro), this framework emerges from years of real-world experience building scalable applications and recognizing critical gaps in existing solutions.

## The Full-Stack Development Problem

Modern applications typically involve juggling multiple technologies, each with its own paradigms:

### Type Safety Boundaries

Even with TypeScript on both frontend and backend, the communication layer—APIs, database queries, client-server interactions—often lacks proper type safety. This leads to:

❌ Runtime errors from mismatched types\
❌ Manual synchronization of types across codebases\
❌ Integration bugs discovered only in production\
❌ Time wasted debugging trivial type mismatches

### Complex State Management

Keeping client state synchronized with server data requires:

❌ Intricate caching strategies\
❌ Manual cache invalidation logic\
❌ Real-time update implementations\
❌ Optimistic update patterns\
❌ Error state handling

Each of these adds complexity and maintenance burden.

### Backend Infrastructure Maze

Building robust backend services means integrating:

❌ Database ORMs\
❌ Caching systems\
❌ Background job queues\
❌ Pub/sub messaging\
❌ Real-time WebSocket servers\
❌ Telemetry and monitoring

Each system requires separate configuration and rarely shares type information.

### Fragmented Developer Experience

Developers constantly switch between:

❌ Different mental models for frontend vs backend\
❌ Multiple toolchains and build processes\
❌ Separate debugging approaches\
❌ Disconnected testing strategies

This context-switching reduces productivity and increases cognitive load.

## Enter Igniter.js: A Unified Solution

Igniter.js addresses these challenges through a **unified, type-safe approach** that treats your entire application as a cohesive system.

<Callout type="success" title="Core Philosophy">
  Igniter.js is built on three principles:

  1. **End-to-End Type Safety**: Every piece of data flowing through your application is type-safe, from database queries to UI components
  2. **Developer Experience First**: Intuitive APIs, excellent tooling, and minimal boilerplate
  3. **Unified Backend Architecture**: All backend services work together seamlessly with shared type safety
</Callout>

## Key Features

### 1. Type-Safe Controllers and Actions

Define your API with complete type safety and automatic validation:

```typescript
// features/users/controllers/users.controller.ts
import { igniter } from '@/igniter'
import { z } from 'zod'

export const userController = igniter.controller({
  path: '/users',
  actions: {
    // Type-safe query with automatic validation
    getUser: igniter.query({
      path: '/:id',
      query: z.object({
        id: z.string().uuid()
      }),
      handler: async ({ request, response, context }) => {
        const user = await context.db.user.findUnique({
          where: { id: request.query.id }
        })

        if (!user) {
          return response.notFound('User not found')
        }

        return response.success(user)
      }
    }),
    
    // Type-safe mutation with validation
    createUser: igniter.mutate({
      path: '/',
      method: 'POST',
      body: z.object({
        name: z.string().min(1),
        email: z.string().email()
      }),
      handler: async ({ request, response, context }) => {
        const user = await context.db.user.create({
          data: request.body
        })
        
        return response.success({ user }, { status: 201 })
      }
    })
  }
})
```

The beauty is on the client side—consuming this API is equally type-safe:

```tsx
'use client'

import { api } from '@/igniter.client'

function UserProfile({ userId }: { userId: string }) {
  // Fully typed with automatic caching and revalidation
  const userQuery = api.users.getUser.useQuery({
    query: { id: userId }
  })
  
  const createUserMutation = api.users.createUser.useMutation({
    onSuccess: (data) => {
      console.log('User created:', data.user)
    }
  })
  
  if (userQuery.isLoading) return <div>Loading...</div>
  if (userQuery.isError) return <div>Error: {userQuery.error.message}</div>
  
  return (
    <div>
      <h1>{userQuery.data?.name}</h1>
      <p>{userQuery.data?.email}</p>
    </div>
  )
}
```

<Callout type="info" title="Zero Code Generation">
  Unlike some solutions, Igniter.js achieves this type safety through TypeScript's type inference—no build step required. Your IDE provides instant autocomplete and error checking.
</Callout>

### 2. Procedures: Reusable Type-Safe Middleware

Create powerful, composable middleware that extends your application context:

```typescript
// procedures/auth.procedure.ts
export const auth = igniter.procedure({
  handler: async (options: { required: boolean }, { response, context }) => {
    const user = await getCurrentUser(context.env.SECRET)

    // If auth is required but there's no user, stop the request
    if (options.required && !user) {
      return response.unauthorized('Authentication required')
    }

    // The returned object merges into context
    // Now context.auth.user is available in controllers!
    return {
      auth: { user }
    }
  }
})

// Usage in controller
export const userController = igniter.controller({
  path: '/users',
  actions: {
    getCurrentUser: igniter.query({
      path: '/me',
      use: [auth({ required: true })], // TypeScript knows context.auth.user exists!
      handler: async ({ context, response }) => {
        const user = context.auth.user // Fully typed!
        return response.success(user)
      }
    })
  }
})
```

### 3. Real-Time Updates by Default

Igniter.js makes real-time synchronization trivial through automatic revalidation:

```typescript
// Backend: Regular query and mutation
export const postsController = igniter.controller({
  path: '/posts',
  actions: {
    list: igniter.query({
      path: '/',
      stream: true, // Enable real-time streaming
      handler: async ({ context, response }) => {
        const posts = await context.db.post.findMany()
        return response.success({ posts })
      }
    }),

    create: igniter.mutate({
      path: '/',
      body: z.object({ 
        title: z.string(), 
        content: z.string() 
      }),
      handler: async ({ body, context, response }) => {
        const newPost = await context.db.post.create({ data: body })

        // Automatically triggers revalidation for all clients!
        return response.created(newPost).revalidate(['posts.list'])
      }
    })
  }
})
```

```tsx
// Frontend: Standard useQuery - automatically updates in real-time
function PostsList() {
  const postsQuery = api.posts.list.useQuery()

  return (
    <ul>
      {postsQuery.data?.posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

// When ANY user creates a post, ALL users see it instantly!
// No WebSockets, no manual refetching, no additional complexity.
```

<Callout type="success" title="Real-Time Made Simple">
  Igniter.js uses Server-Sent Events (SSE) under the hood, providing efficient server-to-client updates without the complexity of WebSocket infrastructure.
</Callout>

### 4. Background Jobs with Type Safety

Handle async processing with a powerful, type-safe job system:

```typescript
// Define jobs with type validation
export const jobs = igniter.jobs.merge({
  emails: igniter.jobs.router({
    jobs: {
      sendWelcome: igniter.jobs.register({
        name: 'sendWelcome',
        input: z.object({
          userId: z.string(),
          email: z.string().email()
        }),
        handler: async ({ input }) => {
          await sendEmail({
            to: input.email,
            template: 'welcome',
            data: { userId: input.userId }
          })
        }
      })
    }
  })
})

// Enqueue from anywhere
export const userController = igniter.controller({
  path: '/users',
  actions: {
    create: igniter.mutate({
      path: '/',
      body: z.object({
        name: z.string(),
        email: z.string().email()
      }),
      handler: async ({ body, context, response }) => {
        const user = await context.db.user.create({ data: body })

        // Enqueue welcome email job with full type safety
        await igniter.jobs.emails.enqueue({
          task: 'sendWelcome',
          input: {
            userId: user.id,
            email: user.email
          }
        })

        return response.success({ user })
      }
    })
  }
})
```

## Framework-Agnostic Architecture

Igniter.js integrates seamlessly with any JavaScript runtime and framework. Write once, deploy anywhere:

<Tabs items={['Next.js', 'Express', 'Bun', 'Cloudflare']} groupId="runtime">
  <Tab value="Next.js">
    ```typescript
    // app/api/[...igniter]/route.ts
    import { igniter } from '@/igniter'

    export const { GET, POST, PUT, DELETE, PATCH } = igniter.nextjs()
    ```
  </Tab>

  <Tab value="Express">
    ```typescript
    // server.ts
    import express from 'express'
    import { igniter } from './igniter'

    const app = express()
    app.use('/api', igniter.express())

    app.listen(3000)
    ```
  </Tab>

  <Tab value="Bun">
    ```typescript
    // server.ts
    import { igniter } from './igniter'

    Bun.serve({
      port: 3000,
      fetch: igniter.fetch
    })
    ```
  </Tab>

  <Tab value="Cloudflare">
    ```typescript
    // worker.ts
    import { igniter } from './igniter'

    export default {
      fetch: igniter.fetch
    }
    ```
  </Tab>
</Tabs>

<Callout type="info" title="Frontend Flexibility">
  Use Igniter.js with React, Vue, Svelte, Angular, React Native, or any frontend framework. The type-safe client adapts to your chosen stack.
</Callout>

## Performance and Scalability

Built for production from day one:

### Performance Features

✅ **Zero Runtime Overhead**: Client code is fully tree-shakeable\
✅ **Minimal Bundle Size**: Only ship what you use\
✅ **Fast Cold Starts**: Optimized for serverless environments\
✅ **Efficient Serialization**: Optimized data transfer\
✅ **Edge-Ready**: Native support for edge runtimes

### Scalability Architecture

✅ **Horizontal Scaling**: Stateless design enables easy scaling\
✅ **Edge Deployment**: Works on Cloudflare Workers, Vercel Edge\
✅ **Background Processing**: Reliable job queues with Redis/BullMQ\
✅ **Real-time Streaming**: Efficient SSE for live data\
✅ **Intelligent Caching**: Built-in query caching with smart invalidation\
✅ **Database Agnostic**: Works with Prisma, Drizzle, or any ORM

## Getting Started

Create a new Igniter.js project in under 2 minutes:

<Steps>
  <Step>
    ### Initialize Project

    ```bash
    npx @igniter-js/cli init my-app
    ```

    Choose your preferred setup:

    * Next.js + React
    * TanStack Start
    * Bun + React
    * Express.js API
    * Custom setup
  </Step>

  <Step>
    ### Install Dependencies

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        cd my-app
        npm install
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        cd my-app
        pnpm install
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        cd my-app
        yarn install
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        cd my-app
        bun install
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Start Development

    ```bash
    npm run dev
    ```

    Your app is now running at `http://localhost:3000` with full type safety!
  </Step>
</Steps>

## Comparison with Existing Solutions

### vs. tRPC

While tRPC provides excellent type safety for APIs, Igniter.js offers:

✅ Integrated job queues\
✅ Real-time updates out of the box\
✅ AI-powered development tools\
✅ More comprehensive DX features

### vs. Next.js

Next.js is a fantastic React framework, but doesn't provide:

✅ Backend abstractions\
✅ Type safety across the full stack\
✅ Built-in state management\
✅ Real-time capabilities

Igniter.js complements Next.js by providing the backend architecture.

### vs. Remix

Remix offers great full-stack capabilities but lacks:

✅ Framework-agnostic design\
✅ The same level of type safety\
✅ AI integration\
✅ Built-in job queues

### vs. T3 Stack

The T3 Stack combines excellent tools but requires:

❌ Significant configuration\
❌ Multiple separate integrations\
❌ Manual setup for queues and real-time

Igniter.js provides all features integrated out of the box.

## What's Next?

Explore the ecosystem:

* [Quick Start Guide](/docs/getting-started/quick-start)
* [Starter Templates](/templates)
* [Core Concepts](/docs/core-concepts)
* [API Reference](/docs/api-reference)
* [Real-Time Guide](/docs/advanced-features/real-time)

## Join the Community

* [GitHub Repository](https://github.com/felipebarcelospro/igniter-js)
* [Documentation](/docs)
* [Discord Community](https://discord.gg/igniterjs)
* [Twitter](https://twitter.com/igniterjs)

## Conclusion

Igniter.js represents a new paradigm in full-stack development where type safety, developer experience, and modern capabilities are fundamental design principles, not afterthoughts.

By eliminating traditional boundaries between frontend and backend, Igniter.js enables you to build more reliable, maintainable, and feature-rich applications with significantly less complexity.

Whether you're building a simple CRUD app, a complex enterprise system, or an AI-powered platform, Igniter.js provides the tools you need to focus on delivering value to your users.

<Callout type="tip" title="Ready to Start?">
  Get started with Igniter.js today and experience the future of full-stack development. Choose a [starter template](/templates) and build your first feature in minutes.
</Callout>

***

*Igniter.js is created and maintained by [Felipe Barcelos](https://github.com/felipebarcelospro) and the open-source community. Thank you to all contributors shaping the future of full-stack development.*


---

# Introducing Igniter Studio: Your Interactive API Development Playground

> Stop switching between tools. Igniter Studio brings interactive API testing, real-time monitoring, and AI-powered insights directly into your development workflow. Built on Scalar, designed for the future.
URL: https://igniterjs.com/blog/introducing-igniter-studio

Modern API development shouldn't require juggling multiple applications. Yet developers constantly switch between their code editor, terminal, and separate API testing tools like Postman or Insomnia. This context-switching destroys focus and slows development.

**Igniter Studio** eliminates this friction by providing a beautiful, interactive API playground built directly into your Igniter.js application. But this is just the beginning—we're building toward a complete AI-powered command center for modern development.

## The Context-Switching Problem

A typical development workflow looks like this:

<Steps>
  <Step>
    ### Write Code

    Make changes in your code editor
  </Step>

  <Step>
    ### Start Server

    Switch to terminal, run development server
  </Step>

  <Step>
    ### Test API

    Switch to Postman/Insomnia, manually configure request
  </Step>

  <Step>
    ### Check Logs

    Switch back to terminal to view logs
  </Step>

  <Step>
    ### Debug Issue

    Switch back to code editor
  </Step>
</Steps>

Each context switch breaks your flow and consumes mental energy. **What if all of this happened in one place?**

## Introducing Igniter Studio

Igniter Studio is an interactive API playground that lives alongside your application, automatically consuming your OpenAPI specification to provide a rich, type-aware testing interface.

Built on [Scalar API Reference](https://github.com/scalar/scalar), it offers a modern, beautiful UI that makes API exploration intuitive and enjoyable.

### Get Started in Seconds

Launch Igniter Studio by adding a single flag to your development command:

```bash
npx @igniter-js/cli dev --docs
```

That's it! Navigate to `/docs` on your local server and you'll see your entire API ready to explore.

<Callout type="success" title="Zero Configuration Required">
  Igniter Studio automatically detects your API structure from the generated OpenAPI specification. No manual setup, no configuration files—it just works.
</Callout>

## See It in Action

Watch how seamlessly Igniter Studio integrates into your development workflow:

<div className="relative aspect-video w-full overflow-hidden rounded-lg border">
  <iframe className="absolute inset-0 h-full w-full" src="https://www.youtube.com/embed/v0BOPH02RBU" title="Igniter Studio Demo" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</div>

## Current Features

### Interactive API Explorer

Browse your entire API structure with an intuitive, searchable interface. Each endpoint displays:

* **Complete type information** derived from your Zod schemas
* **Request/response examples** automatically generated from your types
* **Authentication requirements** clearly documented
* **Parameter descriptions** from your JSDoc comments

### Live API Testing

Test endpoints directly in the browser with:

<Steps>
  <Step>
    ### Smart Request Builder

    Auto-complete for parameters, headers, and request bodies based on your API types
  </Step>

  <Step>
    ### Real-Time Responses

    See responses instantly with syntax highlighting and formatting
  </Step>

  <Step>
    ### Request History

    Access previous requests to quickly iterate on testing
  </Step>

  <Step>
    ### Code Generation

    Export working code samples in multiple languages (cURL, JavaScript, Python, etc.)
  </Step>
</Steps>

### Automatic Documentation

Your API documentation stays in sync with your code because it's generated from the same source of truth:

```typescript
// Your controller automatically generates documentation
export const userController = igniter.controller({
  path: '/users',
  actions: {
    getUser: igniter.query({
      path: '/:id',
      description: 'Retrieve a user by ID', // Shows in Studio
      query: z.object({
        id: z.string().uuid().describe('The user UUID')
      }),
      handler: async ({ request, response, context }) => {
        // Implementation
      }
    })
  }
})
```

This description and parameter documentation automatically appears in Igniter Studio—no separate documentation files to maintain.

## The Vision: Your AI-Powered Command Center

Igniter Studio today is powerful, but it's just the foundation. We're building toward a complete development command center that brings together everything you need to build, test, and monitor your application.

### Coming Soon: Real-Time Monitoring

<Callout type="info" title="Roadmap Feature">
  Currently in development for a future release.
</Callout>

See your application's heartbeat in real-time:

* **Live Request Stream**: Watch API requests as they happen with detailed payload inspection
* **Performance Metrics**: Track response times, error rates, and throughput
* **Error Tracking**: Catch and diagnose issues the moment they occur
* **Request Replay**: Reproduce problematic requests for debugging

### Coming Soon: Queue & Job Management

Visual dashboards for background processing:

* **Job Queue Visualization**: See pending, active, and completed jobs
* **Job Status Monitoring**: Track progress of long-running tasks
* **Manual Job Control**: Retry failed jobs, cancel stuck operations
* **Performance Analytics**: Understand job execution patterns

### Coming Soon: Integrated Telemetry

Turn OpenTelemetry data into actionable insights:

* **Distributed Tracing**: Follow requests across services and operations
* **Performance Profiling**: Identify bottlenecks in your application
* **Custom Metrics**: Track business-specific KPIs
* **Alerting**: Get notified when metrics cross thresholds

### Coming Soon: Custom Dashboards

Create personalized views for your specific needs:

* **Business Metrics**: Track sign-ups, conversions, revenue
* **Technical Health**: Monitor system resources, dependencies
* **Team Dashboards**: Share important metrics across your team
* **Embedded Widgets**: Add dashboard panels to your application UI

## The Game-Changer: Integrated AI Assistant

The most transformative feature on our roadmap is **Lia**, your AI assistant, integrated directly into Igniter Studio.

### Natural Language Development

Imagine debugging and managing your application using conversational language:

<Steps>
  <Step>
    ### Ask Questions

    **You:** "Lia, what was the payload of the last failed request to `/users`?"

    **Lia:** "The last failed request at 14:32:15 had an invalid email format in the request body..."
  </Step>

  <Step>
    ### Execute Commands

    **You:** "Lia, run the test suite for the auth feature."

    **Lia:** "Running tests... 12 passed, 1 failed. The `login` test is failing due to..."
  </Step>

  <Step>
    ### Create Dashboards

    **You:** "Lia, create a dashboard tracking API error rates over 24 hours."

    **Lia:** "Dashboard created. I've added widgets for total errors, error rate trend, and top failing endpoints..."
  </Step>

  <Step>
    ### Get Guidance

    **You:** "Lia, how do I add a new scope to authentication?"

    **Lia:** "To add a new authentication scope, you'll need to modify your auth procedure. Here's how\..."
  </Step>
</Steps>

### Context-Aware Assistance

Unlike generic AI chatbots, Lia has **full context** of your application:

* Real-time access to your code structure
* Live monitoring data from your running application
* Complete request/response history
* Historical performance metrics
* Your specific architectural patterns

This creates an unprecedented development experience where your AI assistant truly understands your application's state and can provide precise, actionable guidance.

## Technical Architecture

Igniter Studio is designed to be lightweight and non-intrusive:

### Development Mode

In development, Studio runs alongside your application:

```typescript
// Automatically enabled with --docs flag
npx @igniter-js/cli dev --docs

// Accessible at http://localhost:3000/docs
```

### Production Deployment

For production, you have options:

<Tabs items={['Disable', 'Protected', 'Separate']} groupId="production-mode">
  <Tab value="Disable">
    Completely disable Studio in production:

    ```typescript
    // igniter.config.ts
    export default {
      studio: {
        enabled: process.env.NODE_ENV === 'development'
      }
    }
    ```
  </Tab>

  <Tab value="Protected">
    Enable Studio with authentication:

    ```typescript
    // igniter.config.ts
    export default {
      studio: {
        enabled: true,
        auth: {
          type: 'basic',
          users: [{ 
            username: process.env.STUDIO_USER,
            password: process.env.STUDIO_PASS 
          }]
        }
      }
    }
    ```
  </Tab>

  <Tab value="Separate">
    Deploy Studio as a separate instance:

    ```bash
    # Deploy only Studio with read-only access
    npx @igniter-js/cli studio --remote
    ```
  </Tab>
</Tabs>

## Integration with Development Workflow

Igniter Studio seamlessly fits into your existing workflow:

### Local Development

```bash
# Start dev server with Studio
npm run dev -- --docs

# Or configure it permanently
# package.json
{
  "scripts": {
    "dev": "igniter dev --docs"
  }
}
```

### Team Collaboration

Share API documentation with your team by deploying Studio:

```bash
# Deploy Studio to a shareable URL
vercel deploy --only-studio

# Or use your existing deployment
# Studio is available at /docs on any environment
```

### CI/CD Integration

Validate API contracts in your pipeline:

```bash
# Generate OpenAPI spec for validation
igniter openapi > spec.json

# Compare with previous version
diff spec.json spec.previous.json
```

## Get Started Today

Igniter Studio is available now in all Igniter.js projects. Start exploring your API in a whole new way:

<Steps>
  <Step>
    ### Start Your Project

    Use any Igniter.js starter template or existing project
  </Step>

  <Step>
    ### Launch Studio

    ```bash
    npx @igniter-js/cli dev --docs
    ```
  </Step>

  <Step>
    ### Open in Browser

    Navigate to `http://localhost:3000/docs`
  </Step>

  <Step>
    ### Start Exploring

    Browse your API, test endpoints, and experience the future of API development
  </Step>
</Steps>

## Starter Templates

Every Igniter.js starter template comes with Studio pre-configured and ready to use:

* [Next.js Full-Stack Starter](/templates/starter-nextjs)
* [TanStack Start Starter](/templates/starter-tanstack-start)
* [Bun + React Starter](/templates/starter-bun-react-app)
* [Express API Starter](/templates/starter-express-rest-api)
* [Bun API Starter](/templates/starter-bun-rest-api)
* [Deno API Starter](/templates/starter-deno-rest-api)

## Share Your Feedback

Igniter Studio is evolving based on your needs. We'd love to hear:

* What features would make your workflow even better?
* What pain points does Studio solve for you?
* What should we prioritize on the roadmap?

Join the conversation:

* [GitHub Discussions](https://github.com/felipebarcelospro/igniter-js/discussions)
* [Discord Community](https://discord.gg/igniterjs)
* [Twitter](https://twitter.com/igniterjs)

## Resources

* [Studio Documentation](/docs/tools/studio)
* [OpenAPI Generation](/docs/advanced-features/openapi)
* [Deployment Guide](/docs/deployment)
* [Starter Templates](/templates)

***

The future of API development is here. Stop juggling tools and start building with Igniter Studio—your new development command center.


---

# Introducing Igniter.js Templates: Production-Ready Starters for Every Stack

> Skip the boilerplate and start building. Our curated collection of production-ready templates gives you the perfect foundation for Next.js, React, Express, Bun, Deno, and more—all with best practices baked in.
URL: https://igniterjs.com/blog/introducing-igniter-templates

Starting a new project shouldn't mean spending hours configuring build tools, setting up databases, implementing authentication, and establishing project structure. Yet that's exactly what developers face every time they begin a new application.

**Igniter.js Templates** eliminate this friction. Our curated collection of production-ready starter templates provides battle-tested foundations that follow industry best practices and leverage the full power of the Igniter.js ecosystem.

## The Problem: Setup Friction Kills Momentum

Every experienced developer knows the pain:

<Steps>
  <Step>
    ### Choose Your Stack

    Research and decide on frameworks, libraries, and tools
  </Step>

  <Step>
    ### Configure Build Tools

    Set up TypeScript, bundlers, linters, formatters
  </Step>

  <Step>
    ### Database Setup

    Configure ORM, migrations, connection pooling
  </Step>

  <Step>
    ### Project Structure

    Establish folder organization and naming conventions
  </Step>

  <Step>
    ### Development Environment

    Docker compose, environment variables, local services
  </Step>

  <Step>
    ### Actually Start Coding

    Finally begin building features (hours or days later)
  </Step>
</Steps>

By the time you're ready to write actual business logic, your initial excitement has often faded. **What if you could skip straight to building features?**

## The Solution: Production-Ready Templates

Igniter.js Templates are not toy examples or minimal boilerplates. They're comprehensive, production-grade starter projects that include:

✅ **Complete Type Safety**: End-to-end TypeScript with strict mode enabled\
✅ **Database Integration**: Prisma ORM pre-configured with PostgreSQL\
✅ **Modern Tooling**: Latest versions of all dependencies\
✅ **Docker Development**: One-command local environment setup\
✅ **Best Practices**: Established patterns for scaling\
✅ **Feature Examples**: Real implementations to learn from\
✅ **Testing Setup**: Vitest configured and ready\
✅ **CI/CD Ready**: GitHub Actions workflows included

## Template Collection

Our initial collection covers the most popular stacks and use cases:

### Full-Stack Applications

<Callout type="info" title="Complete Solutions">
  These templates include both frontend and backend, fully integrated with Igniter.js for end-to-end type safety.
</Callout>

#### Next.js Full-Stack App

The most comprehensive template, perfect for building modern web applications.

**Stack**: Next.js 15, React 19, Prisma, PostgreSQL, Redis, BullMQ, Tailwind CSS

**Best For**:

* SaaS applications
* Content-driven websites
* Admin dashboards
* Customer portals

**Key Features**:

* App Router with Server Components
* Real-time updates via SSE
* Background job processing
* Authentication ready
* shadcn/ui components

```bash
npx @igniter-js/cli init my-app --template nextjs
```

[View Template Details](/templates/starter-nextjs)

***

#### TanStack Start Full-Stack App

Modern React framework with powerful file-based routing and data fetching.

**Stack**: TanStack Start, React 19, Prisma, PostgreSQL, Tailwind CSS

**Best For**:

* SPAs with complex routing
* Apps requiring fine-grained data loading
* Projects prioritizing performance

**Key Features**:

* File-based routing
* Automatic code splitting
* Optimized data loading
* Type-safe navigation

```bash
npx @igniter-js/cli init my-app --template tanstack-start
```

[View Template Details](/templates/starter-tanstack-start)

***

#### Bun + React SPA

Lightning-fast development with Bun's revolutionary runtime.

**Stack**: Bun, React 18, Prisma, PostgreSQL, Tailwind CSS

**Best For**:

* Single-page applications
* Projects prioritizing speed
* Node.js alternative seekers

**Key Features**:

* Instant hot reload with Bun
* Native TypeScript support
* Minimal configuration
* 3x faster install times

```bash
npx @igniter-js/cli init my-app --template bun-react
```

[View Template Details](/templates/starter-bun-react-app)

### Backend APIs

<Callout type="success" title="Framework Agnostic">
  Build APIs that work with any frontend framework—React, Vue, Svelte, Angular, or mobile applications.
</Callout>

#### Express REST API

The classic Node.js framework, enhanced with Igniter.js type safety.

**Stack**: Express.js, TypeScript, Prisma, PostgreSQL

**Best For**:

* Traditional REST APIs
* Microservices
* Teams familiar with Express
* Projects requiring Express middleware

**Key Features**:

* Express ecosystem compatibility
* Middleware support
* Well-documented patterns
* Easy deployment

```bash
npx @igniter-js/cli init my-api --template express-api
```

[View Template Details](/templates/starter-express-rest-api)

***

#### Bun REST API

Modern backend powered by Bun's performance-first runtime.

**Stack**: Bun, TypeScript, Prisma, PostgreSQL

**Best For**:

* High-performance APIs
* WebSocket-heavy applications
* Modern backend architectures

**Key Features**:

* Native WebSocket support
* Built-in testing framework
* Fast cold starts
* Minimal dependencies

```bash
npx @igniter-js/cli init my-api --template bun-api
```

[View Template Details](/templates/starter-bun-rest-api)

***

#### Deno REST API

Secure-by-default runtime with modern JavaScript features.

**Stack**: Deno, TypeScript, Prisma, PostgreSQL

**Best For**:

* Security-focused applications
* Edge deployments
* Teams wanting modern defaults

**Key Features**:

* Secure by default
* Native TypeScript
* Standard library included
* Deno Deploy ready

```bash
npx @igniter-js/cli init my-api --template deno-api
```

[View Template Details](/templates/starter-deno-rest-api)

## Consistent Architecture Across Templates

Every template follows the same proven architecture, making it easy to switch between stacks or apply patterns across projects:

### Feature-Based Organization

All templates use a scalable, feature-based folder structure:

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="features">
      <Folder name="auth">
        <File name="auth.controller.ts" />

        <File name="auth.procedure.ts" />

        <File name="auth.schema.ts" />
      </Folder>

      <Folder name="users">
        <File name="users.controller.ts" />

        <File name="users.procedure.ts" />

        <File name="users.schema.ts" />
      </Folder>
    </Folder>

    <Folder name="lib">
      <File name="database.ts" />

      <File name="logger.ts" />
    </Folder>

    <File name="igniter.ts" />

    <File name="igniter.router.ts" />

    <File name="igniter.client.ts" />
  </Folder>
</Files>

### Shared Conventions

**Controller Pattern**: Type-safe API endpoints with automatic validation

```typescript
export const userController = igniter.controller({
  path: '/users',
  actions: {
    list: igniter.query({
      path: '/',
      handler: async ({ context, response }) => {
        const users = await context.db.user.findMany()
        return response.success({ users })
      }
    })
  }
})
```

**Procedure Pattern**: Reusable business logic and middleware

```typescript
export const auth = igniter.procedure({
  handler: async (options, { context, response }) => {
    const user = await getCurrentUser(context)
    if (options.required && !user) {
      return response.unauthorized()
    }
    return { auth: { user } }
  }
})
```

**Schema Pattern**: Centralized validation with Zod

```typescript
export const createUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email()
})
```

## Getting Started: 2-Minute Setup

Every template includes comprehensive setup instructions, but the basics are the same:

<Steps>
  <Step>
    ### Initialize Project

    <Tabs items={['Interactive', 'Direct']} groupId="init-method">
      <Tab value="Interactive">
        ```bash
        npx @igniter-js/cli init my-app
        # Follow prompts to select template
        ```
      </Tab>

      <Tab value="Direct">
        ```bash
        npx @igniter-js/cli init my-app --template nextjs
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Install Dependencies

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        cd my-app
        npm install
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        cd my-app
        pnpm install
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        cd my-app
        yarn install
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        cd my-app
        bun install
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Start Local Services

    ```bash
    # Start PostgreSQL and Redis with Docker
    docker-compose up -d
    ```
  </Step>

  <Step>
    ### Configure Environment

    ```bash
    # Copy example environment file
    cp .env.example .env

    # Edit .env with your settings
    # DATABASE_URL and REDIS_URL are pre-configured for Docker
    ```
  </Step>

  <Step>
    ### Initialize Database

    ```bash
    npx prisma db push
    ```
  </Step>

  <Step>
    ### Start Development Server

    ```bash
    npm run dev
    ```

    Your application is now running at `http://localhost:3000`
  </Step>
</Steps>

<Callout type="success" title="Ready to Build">
  In under 2 minutes, you have a fully functional application with database, caching, type-safe API, and modern frontend—all working together.
</Callout>

## What's Included in Every Template

### Development Experience

**Instant Feedback**: Hot reload on every change\
**Type Safety**: Full TypeScript coverage with strict mode\
**Code Quality**: ESLint and Prettier pre-configured\
**Testing**: Vitest setup with example tests\
**Debugging**: VS Code launch configurations included

### Production Readiness

**Environment Management**: `.env` files with validation\
**Error Handling**: Comprehensive error boundaries\
**Logging**: Structured logging setup\
**Security**: CORS, rate limiting, input validation\
**Performance**: Built-in caching strategies

### Documentation

**README**: Detailed setup and usage instructions\
**AGENT.md**: AI assistant integration guide\
**Code Comments**: Well-documented examples\
**Architecture Docs**: Explanation of patterns and decisions

## Contributing Your Own Template

We welcome community contributions! Share your expertise by creating templates for new frameworks, use cases, or technology stacks.

<Steps>
  <Step>
    ### Fork and Clone

    ```bash
    git clone https://github.com/felipebarcelospro/igniter-js.git
    cd igniter-js
    ```
  </Step>

  <Step>
    ### Create Template Directory

    ```bash
    mkdir apps/starter-your-template-name
    cd apps/starter-your-template-name
    ```
  </Step>

  <Step>
    ### Build Your Template

    Include these essentials:

    * Comprehensive `README.md` with setup instructions
    * `AGENT.md` describing template purpose and features
    * TypeScript with strict mode enabled
    * Error handling and validation throughout
    * Security best practices
    * Example features demonstrating patterns
  </Step>

  <Step>
    ### Add Documentation

    Create template documentation page:

    ```bash
    mkdir apps/docs/content/templates/
    # Create MDX file with frontmatter and details
    ```
  </Step>

  <Step>
    ### Test Thoroughly

    Verify:

    * Clean installation process
    * All dependencies install correctly
    * Development server starts without errors
    * Build process completes successfully
    * TypeScript compilation passes
    * Tests run and pass
  </Step>

  <Step>
    ### Submit Pull Request

    Include:

    * Detailed description of template features
    * Target use cases and audience
    * Any unique setup requirements
    * Screenshots or demo links
  </Step>
</Steps>

<Callout type="info" title="Quality Standards">
  We review all template submissions to ensure they meet our quality standards and provide genuine value to the community. Thank you for helping make Igniter.js better!
</Callout>

## Community Templates

Beyond our official templates, the community is building amazing starters for specific use cases:

* **E-commerce Platform**: Full shopping cart, payments, and inventory
* **SaaS Boilerplate**: Multi-tenancy, billing, and user management
* **Mobile API**: Optimized for React Native and Flutter apps
* **Real-Time Chat**: WebSocket and SSE implementation
* **Analytics Dashboard**: Data visualization and reporting

Browse community templates and submit your own at [igniterjs.com/templates/community](/templates/community)

## What's Next?

We're continuously expanding our template collection based on community needs. Upcoming templates include:

* **Monorepo Starter**: Turborepo setup with shared packages
* **GraphQL API**: Apollo Server integration
* **Mobile Full-Stack**: React Native with Igniter.js backend
* **Electron Desktop**: Cross-platform desktop applications
* **Chrome Extension**: Browser extension with Igniter.js API

<Callout type="tip" title="Vote on Priorities">
  Help us prioritize by voting on template requests in our [GitHub Discussions](https://github.com/felipebarcelospro/igniter-js/discussions).
</Callout>

## Try It Today

Stop spending hours on setup. Start building features in minutes with Igniter.js Templates:

```bash
# Choose your adventure
npx @igniter-js/cli init my-awesome-app

# Get coding immediately
cd my-awesome-app
npm run dev
```

Join thousands of developers who are already building faster with production-ready templates.

## Resources

* [Template Gallery](/templates)
* [CLI Documentation](/docs/cli)
* [Template Architecture Guide](/docs/templates/architecture)
* [Contributing Guide](https://github.com/felipebarcelospro/igniter-js/blob/main/CONTRIBUTING.md)

## Community

Share what you're building and get help from the community:

* [Discord Community](https://discord.gg/igniterjs)
* [GitHub Discussions](https://github.com/felipebarcelospro/igniter-js/discussions)
* [Twitter](https://twitter.com/igniterjs)

***

Your next great project is just one command away. Choose a template and start building today.


---

# Build a Production-Ready Real-Time Chat with Igniter.js and Next.js

> Learn how to build a fully type-safe, real-time chat application from scratch using Igniter.js, Next.js, Prisma, and Server-Sent Events. Complete tutorial with live demo and source code.
URL: https://igniterjs.com/blog/real-time-chat-with-igniterjs

Real-time features have become essential in modern web applications. Users expect instant updates without manual refreshing, whether it's a chat room, live notifications, or collaborative editing. In this comprehensive tutorial, you'll build a production-ready, type-safe chat application that showcases the power of Igniter.js's real-time capabilities.

<Callout type="success" title="What You'll Build">
  A fully functional real-time chat application with:

  * **End-to-end type safety** from database to UI components
  * **Instant message delivery** using Server-Sent Events (SSE)
  * **Automatic UI synchronization** across all connected clients
  * **Production-ready architecture** with Prisma and PostgreSQL
  * **Beautiful, responsive interface** built with Tailwind CSS

  **Live Demo**: [igniter-js-sample-realtime-chat.vercel.app](https://igniter-js-sample-realtime-chat.vercel.app/)
</Callout>

## Why Server-Sent Events?

While WebSockets have traditionally been the go-to for real-time features, many use cases are actually **server-to-client dominant**. A chat application is perfect example: users send messages (client-to-server), and the server pushes updates to all clients (server-to-client).

**Server-Sent Events (SSE)** excel in this scenario:

✅ **Simpler than WebSockets**: Built on HTTP, easier to implement and debug\
✅ **Efficient**: Single long-lived connection per client\
✅ **Automatic reconnection**: Built into the browser spec\
✅ **Works everywhere**: No special server infrastructure needed\
✅ **Firewall-friendly**: Uses standard HTTP connections

<Callout type="info" title="When to Use SSE vs WebSockets">
  **Use SSE when**: Server primarily pushes data to clients (notifications, live feeds, chat)\
  **Use WebSockets when**: You need true bidirectional communication (gaming, video calls)
</Callout>

## Prerequisites

Before starting, ensure you have:

* **Node.js** v18 or higher
* **npm**, **pnpm**, **yarn**, or **bun** package manager
* **Docker** (for local PostgreSQL database)
* Basic knowledge of TypeScript and React

## Project Setup

### Step 1: Initialize the Project

Use the Igniter.js CLI to scaffold a new Next.js application:

```bash
npx @igniter-js/cli init realtime-chat
```

<Steps>
  <Step>
    ### Choose Template

    Select **Next.js App Router** when prompted
  </Step>

  <Step>
    ### Navigate to Project

    ```bash
    cd realtime-chat
    ```
  </Step>

  <Step>
    ### Install Dependencies

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        npm install
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm install
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn install
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun install
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

### Step 2: Database Schema

Define your data model using Prisma. Open `prisma/schema.prisma` and replace its content:

```prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Message {
  id        String   @id @default(uuid())
  content   String
  sender    String
  
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@map("messages")
}
```

This simple schema stores messages with their content, sender name, and timestamps.

### Step 3: Environment Configuration

Create a `.env` file in your project root:

```bash
# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/chat?schema=public"

# App
NEXT_PUBLIC_APP_URL="http://localhost:3000"
```

### Step 4: Start Local Database

If you don't have PostgreSQL running, use Docker:

```bash
docker run --name chat-db \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=chat \
  -p 5432:5432 \
  -d postgres:16
```

Or use the included `docker-compose.yml`:

```bash
docker-compose up -d
```

### Step 5: Apply Database Schema

Sync your Prisma schema with the database:

```bash
npx prisma db push
```

<Callout type="success">
  Your project foundation is ready! Let's build the backend.
</Callout>

## Building the Backend API

### Step 6: Generate the Message Feature

Igniter.js CLI can scaffold complete features from your Prisma schema:

```bash
npx @igniter-js/cli generate feature message --schema prisma:Message
```

This creates:

<Files>
  <Folder name="src/features/message" defaultOpen>
    <Folder name="controllers">
      <File name="message.controller.ts" />
    </Folder>

    <Folder name="procedures">
      <File name="message.procedure.ts" />
    </Folder>

    <Folder name="schema">
      <File name="message.schema.ts" />
    </Folder>
  </Folder>
</Files>

The generator creates:

* **Controller**: CRUD operations for messages
* **Procedure**: Reusable repository pattern for database access
* **Schema**: Zod validation schemas derived from Prisma

### Step 7: Enable Real-Time Streaming

Open `src/features/message/controllers/message.controller.ts` and modify the `list` action:

```typescript
import { igniter } from '@/igniter'
import { messageProcedure } from '../procedures/message.procedure'

export const messageController = igniter.controller({
  path: '/messages',
  actions: {
    // Enable streaming for real-time updates
    list: igniter.query({
      name: 'list',
      description: 'List all messages with real-time updates',
      path: '/',
      stream: true, // ← This enables SSE!
      use: [messageProcedure()],
      handler: async ({ context, response }) => {
        const messages = await context.messageRepository.findAll()
        return response.success(messages)
      }
    }),
    
    // ... other generated actions
  }
})
```

The `stream: true` flag transforms this endpoint into an SSE stream that clients can subscribe to.

### Step 8: Add Real-Time Revalidation

When a new message is created, we want all connected clients to receive it instantly. Modify the `create` action:

```typescript
export const messageController = igniter.controller({
  path: '/messages',
  actions: {
    list: igniter.query({
      // ... list action from above
    }),

    create: igniter.mutation({
      name: 'create',
      description: 'Create a new message',
      path: '/',
      method: 'POST',
      body: z.object({
        content: z.string().min(1, 'Message cannot be empty'),
        sender: z.string().min(1, 'Sender name is required')
      }),
      use: [messageProcedure()],
      handler: async ({ request, context, response }) => {
        // Create the message
        const message = await context.messageRepository.create(request.body)

        // Trigger revalidation for all connected clients
        return response.created(message).revalidate(['message.list'])
      }
    })
  }
})
```

The `.revalidate(['message.list'])` call tells Igniter.js to notify all clients subscribed to the `message.list` stream that new data is available.

### Step 9: Register the Controller

Open `src/igniter.router.ts` and add the message controller:

```typescript
import { igniter } from '@/igniter'
import { messageController } from '@/features/message/controllers/message.controller'

export const AppRouter = igniter.router({
  controllers: {
    message: messageController
  }
})

export type AppRouter = typeof AppRouter
```

<Callout type="success" title="Backend Complete">
  Your backend API is now fully functional with real-time capabilities! Let's test it before building the frontend.
</Callout>

## Testing the Backend

Before building the UI, verify your API works correctly:

### Test Creating a Message

```bash
curl -X POST http://localhost:3000/api/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello, world!",
    "sender": "TestUser"
  }'
```

### Test Listing Messages

```bash
curl http://localhost:3000/api/v1/messages
```

### Test SSE Stream

```bash
curl -N http://localhost:3000/api/v1/messages/stream
```

You should see a connection stay open, ready to receive updates.

## Building the Frontend

### Step 10: Create the Chat Component

Create `src/features/message/components/chat.tsx`:

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { api } from '@/igniter.client'
import { Button } from '@/components/ui/button'
import {
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from '@/components/ui/card'
import { Input } from '@/components/ui/input'
import { ScrollArea } from '@/components/ui/scroll-area'
import { Send } from 'lucide-react'

export function Chat() {
  const [sender, setSender] = useState('')
  const [message, setMessage] = useState('')
  const [isSenderSet, setIsSenderSet] = useState(false)

  const scrollAreaRef = useRef<HTMLDivElement>(null)

  // Fetch messages with automatic real-time updates
  const { data } = api.message.list.useQuery({
    refetchOnWindowFocus: false
  })

  const messages = data || []

  // Mutation for creating messages
  const createMessage = api.message.create.useMutation()

  // Load sender from localStorage on mount
  useEffect(() => {
    const storedSender = localStorage.getItem('chat-sender')
    if (storedSender) {
      setSender(storedSender)
      setIsSenderSet(true)
    }
  }, [])

  // Auto-scroll to bottom when new messages arrive
  useEffect(() => {
    if (scrollAreaRef.current) {
      const scrollElement = scrollAreaRef.current.querySelector('div > div')
      if (scrollElement) {
        scrollElement.scrollTo({
          top: scrollElement.scrollHeight,
          behavior: 'smooth'
        })
      }
    }
  }, [messages])

  const handleSendMessage = async (e: React.FormEvent) => {
    e.preventDefault()
    if (message.trim() && sender.trim()) {
      await createMessage.mutate({
        body: {
          content: message,
          sender: sender
        }
      })
      setMessage('')
    }
  }

  const handleSetSender = () => {
    if (sender.trim()) {
      localStorage.setItem('chat-sender', sender.trim())
      setIsSenderSet(true)
    }
  }

  return (
    <div className="relative flex flex-col">
      <Card className="w-full rounded-none border-none flex-1 flex flex-col">
        <CardHeader className="border-b">
          <CardTitle>Real-Time Chat with Igniter.js</CardTitle>
        </CardHeader>
        
        <CardContent className="px-4 py-0">
          <ScrollArea 
            className="w-full h-[calc(100vh-16rem)]" 
            ref={scrollAreaRef}
          >
            <div className="space-y-4 py-4">
              {messages.map((msg: any) => (
                <div
                  key={msg.id}
                  className={`flex ${
                    msg.sender === sender 
                      ? 'justify-end' 
                      : 'justify-start'
                  }`}
                >
                  <div
                    className={`p-3 rounded-lg max-w-xs ${
                      msg.sender === sender
                        ? 'bg-primary text-primary-foreground'
                        : 'bg-muted'
                    }`}
                  >
                    <p className="text-sm font-bold">{msg.sender}</p>
                    <p>{msg.content}</p>
                    <p className="text-xs text-right opacity-70 mt-1">
                      {new Date(msg.createdAt).toLocaleTimeString()}
                    </p>
                  </div>
                </div>
              ))}
            </div>
          </ScrollArea>

          <form
            onSubmit={handleSendMessage}
            className="flex w-full items-center space-x-2 py-4"
          >
            <Input
              value={message}
              onChange={(e) => setMessage(e.target.value)}
              placeholder="Type a message..."
              disabled={!isSenderSet}
            />
            <Button
              type="submit"
              disabled={createMessage.isLoading || !isSenderSet}
            >
              <Send className="h-4 w-4" />
            </Button>
          </form>
        </CardContent>
      </Card>

      {/* Name entry modal */}
      {!isSenderSet && (
        <div className="absolute inset-0 z-10 flex items-center justify-center bg-background/80 backdrop-blur-sm">
          <Card className="w-full max-w-sm">
            <CardHeader>
              <CardTitle>Welcome!</CardTitle>
            </CardHeader>
            <CardContent>
              <div className="flex w-full items-center space-x-2">
                <Input
                  value={sender}
                  onChange={(e) => setSender(e.target.value)}
                  placeholder="Enter your name..."
                  onKeyDown={(e) => e.key === 'Enter' && handleSetSender()}
                />
                <Button onClick={handleSetSender}>Join Chat</Button>
              </div>
            </CardContent>
          </Card>
        </div>
      )}
    </div>
  )
}
```

### Understanding the Component

Let's break down the key parts:

**1. Message Query with Auto-Updates**

```typescript
const { data } = api.message.list.useQuery({
  refetchOnWindowFocus: false
})
```

This hook:

* Fetches initial messages on mount
* Automatically refetches when `.revalidate()` is triggered on the backend
* Provides loading and error states
* Caches results for performance

**2. Message Creation Mutation**

```typescript
const createMessage = api.message.create.useMutation()
```

This hook:

* Sends messages to the backend
* Provides loading state during submission
* Handles errors gracefully
* Triggers automatic revalidation on success

**3. Auto-Scroll Behavior**

```typescript
useEffect(() => {
  // Scroll to bottom when messages update
}, [messages])
```

Ensures users always see the latest messages without manual scrolling.

### Step 11: Add to Page

Open `src/app/page.tsx` and use the Chat component:

```tsx
import { Chat } from '@/features/message/components/chat'

export default function HomePage() {
  return (
    <main className="container mx-auto">
      <Chat />
    </main>
  )
}
```

## See It in Action

<Steps>
  <Step>
    ### Start Development Server

    ```bash
    npm run dev
    ```
  </Step>

  <Step>
    ### Open Multiple Windows

    Open `http://localhost:3000` in two browser windows side-by-side
  </Step>

  <Step>
    ### Test Real-Time Updates

    Type a message in one window and watch it appear instantly in both!
  </Step>
</Steps>

<Callout type="success" title="Congratulations!">
  You've built a production-ready, type-safe, real-time chat application! Messages appear instantly across all connected clients with zero manual synchronization.
</Callout>

## How It Works: Under the Hood

### The Real-Time Flow

<Steps>
  <Step>
    ### Client Subscribes

    When `useQuery()` is called with a streamed endpoint, the client opens an SSE connection
  </Step>

  <Step>
    ### User Sends Message

    Client calls `createMessage.mutate()`, sending data to the backend
  </Step>

  <Step>
    ### Backend Processes

    Controller creates the message and calls `.revalidate(['message.list'])`
  </Step>

  <Step>
    ### Server Notifies Clients

    Igniter.js sends a revalidation event through the SSE connection
  </Step>

  <Step>
    ### Clients Refetch

    All subscribed clients automatically refetch the latest messages
  </Step>

  <Step>
    ### UI Updates

    React re-renders with new data, showing the message to all users
  </Step>
</Steps>

### Type Safety Throughout

```typescript
// Backend defines the contract
export const messageController = igniter.controller({
  // ... controller definition
})

// Frontend gets automatic types
api.message.list.useQuery() // ← TypeScript knows the return type!
api.message.create.useMutation() // ← TypeScript validates the body!
```

No code generation, no manual type definitions—pure TypeScript inference.

## Production Deployment

### Environment Variables

Update `.env` for production:

```bash
DATABASE_URL="postgresql://user:pass@host:5432/db"
NEXT_PUBLIC_APP_URL="https://your-domain.com"
```

### Scaling Considerations

#### Single Server

For small-to-medium apps, a single server handles SSE connections efficiently.

#### Multiple Servers (Horizontal Scaling)

For larger apps, use Redis for pub/sub across servers:

```bash
npm install @igniter-js/adapter-redis ioredis
```

```typescript
// src/igniter.ts
import { redisStoreAdapter } from '@igniter-js/adapter-redis'
import Redis from 'ioredis'

const redis = new Redis(process.env.REDIS_URL)

export const igniter = createIgniter({
  store: redisStoreAdapter({ client: redis })
})
```

Now `.revalidate()` publishes to Redis, and all server instances receive updates.

### Deploy to Vercel

```bash
# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod
```

Your chat app is now live with full real-time capabilities!

## Advanced Features

### Add Message Persistence

Already included! Messages are stored in PostgreSQL via Prisma.

### Add User Authentication

Integrate an auth procedure:

```typescript
export const messageController = igniter.controller({
  path: '/messages',
  actions: {
    create: igniter.mutation({
      use: [auth({ required: true })],
      handler: async ({ context, response }) => {
        // context.auth.user is now available
        const message = await context.db.message.create({
          data: {
            content: request.body.content,
            sender: context.auth.user.name
          }
        })
        return response.created(message).revalidate(['message.list'])
      }
    })
  }
})
```

### Add Typing Indicators

Extend the schema and use ephemeral events:

```typescript
// Publish typing event without storing in DB
igniter.realtime.publish('message.typing', {
  sender: context.auth.user.name,
  isTyping: true
})
```

### Add Message Reactions

Add a reactions field to the schema and create a new mutation for toggling reactions.

## Troubleshooting

<Accordions>
  <Accordion title="Messages don't appear in real-time">
    **Check**:

    * `stream: true` is set on the `list` action
    * `.revalidate(['message.list'])` is called in the `create` mutation
    * Browser DevTools Network tab shows an open SSE connection to `/api/v1/messages`
  </Accordion>

  <Accordion title="Type errors in the client">
    **Solution**:

    * Restart TypeScript server in your IDE
    * Ensure `igniter.router.ts` exports `AppRouter` type
    * Check that `igniter.client.ts` imports the router type correctly
  </Accordion>

  <Accordion title="Database connection errors">
    **Check**:

    * PostgreSQL is running (`docker ps`)
    * `DATABASE_URL` in `.env` is correct
    * Run `npx prisma db push` to sync schema
  </Accordion>
</Accordions>

## Next Steps

Explore more Igniter.js features:

* [Background Jobs](/docs/features/jobs) - Process tasks asynchronously
* [Authentication](/docs/features/auth) - Add user authentication
* [File Uploads](/docs/features/uploads) - Handle file uploads
* [WebSockets](/docs/advanced-features/websockets) - For bidirectional communication
* [Testing](/docs/testing) - Write tests for your features

## Resources

* **[Live Demo](https://igniter-js-sample-realtime-chat.vercel.app/)**
* **[Source Code](https://github.com/felipebarcelospro/igniter-js/tree/main/apps/sample-realtime-chat)**
* [Real-Time Documentation](/docs/advanced-features/real-time)
* [useQuery Hook](/docs/client/use-query)
* [useMutation Hook](/docs/client/use-mutation)
* [Server-Sent Events Spec](https://html.spec.whatwg.org/multipage/server-sent-events.html)

***

You've just built a production-ready real-time application with complete type safety and minimal code. This same pattern scales to notifications, live dashboards, collaborative editing, and any feature requiring instant updates.

**Happy building with Igniter.js!** 🚀


---


# Documentation

Complete documentation for Igniter.js framework

---

# API Reference

> Complete API reference for @igniter-js/agents. All builders, types, error codes, adapters, and utility functions with parameter tables and examples.
URL: https://igniterjs.com/docs/agents/api-reference

## API Reference

Complete reference for every public API in `@igniter-js/agents`.

***

## Imports

```typescript
import {
  // Builders
  IgniterAgent,
  IgniterAgentManager,
  IgniterAgentTool,
  IgniterAgentToolset,
  IgniterAgentMCPClient,
  IgniterAgentPrompt,

  // Adapters
  IgniterAgentInMemoryAdapter,
  IgniterAgentJSONFileAdapter,

  // Errors
  IgniterAgentError,
  IgniterAgentConfigError,
  IgniterAgentMCPError,
  IgniterAgentToolError,
  IgniterAgentMemoryError,
  IgniterAgentAdapterError,
  IgniterAgentErrorCode,
  isIgniterAgentError,
  isIgniterAgentMCPError,
  isIgniterAgentToolError,

  // Types
  type IgniterAgentHooks,
  type IgniterAgentMemoryConfig,
  type IgniterAgentGenerateOptions,
  type IgniterAgentStreamOptions,
  type IgniterAgentBuiltAgent,
  type IgniterAgentBuiltTool,
  type IgniterAgentBuiltToolset,
} from '@igniter-js/agents'
```

***

## IgniterAgent

Primary entry point for creating AI agents.

### `IgniterAgent.create(name)`

Creates a new agent builder.

| Parameter | Type     | Required | Description       |
| --------- | -------- | -------- | ----------------- |
| `name`    | `string` | Yes      | Unique agent name |

### Builder Methods

| Method                       | Signature                                                        | Description                                                  |
| ---------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------ |
| `.withModel(model)`          | `(model: LanguageModel) => Builder`                              | Sets the AI language model. Accepts any Vercel AI SDK model. |
| `.withPrompt(prompt)`        | `(prompt: IgniterAgentPromptTemplate) => Builder`                | Sets the system prompt template.                             |
| `.withContextSchema(schema)` | `(schema: ZodSchema) => Builder`                                 | Sets Zod schema for type-safe context.                       |
| `.addToolset(toolset)`       | `(toolset: IgniterAgentToolset) => Builder`                      | Registers a custom toolset.                                  |
| `.addMCP(config)`            | `(config: IgniterAgentMCPConfigUnion) => Builder`                | Registers an MCP client configuration.                       |
| `.withMemory(config)`        | `(config: IgniterAgentMemoryConfig) => Builder`                  | Configures persistent memory.                                |
| `.withLogger(logger)`        | `(logger: IgniterLogger) => Builder`                             | Attaches a logger instance.                                  |
| `.withTelemetry(telemetry)`  | `(telemetry: IgniterTelemetryManager) => Builder`                | Attaches a telemetry manager.                                |
| `.onAgentStart(cb)`          | `(name: string) => void`                                         | Fired when agent starts.                                     |
| `.onAgentError(cb)`          | `(name: string, error: Error) => void`                           | Fired on agent error.                                        |
| `.onToolCallStart(cb)`       | `(agentName: string, toolName: string, input: unknown) => void`  | Fired before tool execution.                                 |
| `.onToolCallEnd(cb)`         | `(agentName: string, toolName: string, output: unknown) => void` | Fired after successful tool execution.                       |
| `.onToolCallError(cb)`       | `(agentName: string, toolName: string, error: Error) => void`    | Fired on tool execution failure.                             |
| `.onMCPStart(cb)`            | `(agentName: string, mcpName: string) => void`                   | Fired before MCP connection.                                 |
| `.onMCPError(cb)`            | `(agentName: string, mcpName: string, error: Error) => void`     | Fired on MCP connection failure.                             |
| `.build()`                   | `() => IgniterAgentBuiltAgent`                                   | Builds the agent.                                            |

### Built Agent Methods

| Method                        | Signature                                                               | Description                                                         |                                 |
| ----------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------- |
| `.start()`                    | `() => Promise<void>`                                                   | Initializes MCP connections. Must be called before generate/stream. |                                 |
| `.stop()`                     | `() => Promise<void>`                                                   | Disconnects MCP connections gracefully.                             |                                 |
| `.generate(options)`          | `(options: IgniterAgentGenerateOptions) => Promise<IgniterAgentOutput>` | Generates a response.                                               |                                 |
| `.stream(options)`            | `(options: IgniterAgentStreamOptions) => Promise<Stream>`               | Streams a response.                                                 |                                 |
| `.getName()`                  | `() => string`                                                          | Returns the agent name.                                             |                                 |
| `.getConfig()`                | `() => Partial<IgniterAgentConfig>`                                     | Returns current config.                                             |                                 |
| `.getToolsets()`              | `() => Record<string, IgniterAgentToolset>`                             | Returns toolsets (including MCP).                                   |                                 |
| `.attachLogger(logger)`       | `(logger?: IgniterLogger) => void`                                      | Attaches logger at runtime.                                         |                                 |
| `.attachTelemetry(telemetry)` | `(telemetry?: IgniterTelemetryManager) => void`                         | Attaches telemetry at runtime.                                      |                                 |
| `.attachHooks(hooks)`         | `(hooks?: IgniterAgentHooks) => void`                                   | Attaches hooks at runtime.                                          |                                 |
| `.memory`                     | \`IgniterAgentMemoryCore                                                | undefined\`                                                         | Memory runtime (if configured). |

### `IgniterAgentGenerateOptions`

| Field      | Type                      | Required | Description                                     |
| ---------- | ------------------------- | -------- | ----------------------------------------------- |
| `chatId`   | `string`                  | Yes      | Unique conversation identifier                  |
| `userId`   | `string`                  | Yes      | User identifier for memory scoping              |
| `context`  | `Record<string, unknown>` | Yes      | Context data (typed if schema set)              |
| `message`  | `{ role, content }`       | No       | Single message (use `message` OR `messages`)    |
| `messages` | `ModelMessage[]`          | No       | Multiple messages (use `message` OR `messages`) |

### `IgniterAgentOutput`

| Field          | Type                 | Description                 |
| -------------- | -------------------- | --------------------------- |
| `content`      | `string`             | The generated text response |
| `toolCalls`    | `ToolCall[]`         | Tools the AI called         |
| `toolResults`  | `ToolResult[]`       | Results from tool calls     |
| `finishReason` | `string`             | Why generation stopped      |
| `usage`        | `LanguageModelUsage` | Token usage statistics      |
| `messages`     | `ModelMessage[]`     | Full message history        |

***

## IgniterAgentManager

Orchestrates multiple agents with shared resources.

### `IgniterAgentManager.create()`

Creates a new manager builder.

### Builder Methods

| Method                       | Signature                                         | Description                                            |
| ---------------------------- | ------------------------------------------------- | ------------------------------------------------------ |
| `.addAgent(name, agent)`     | `(name: string, agent: BuiltAgent) => Builder`    | Registers an agent. Type-safe — names tracked in type. |
| `.withLogger(logger)`        | `(logger: IgniterLogger) => Builder`              | Shared logger for all agents.                          |
| `.withTelemetry(telemetry)`  | `(telemetry: IgniterTelemetryManager) => Builder` | Shared telemetry for all agents.                       |
| `.withAutoStart(bool)`       | `(bool: boolean) => Builder`                      | Auto-start on registration (default: false).           |
| `.withContinueOnError(bool)` | `(bool: boolean) => Builder`                      | Continue batch start on error (default: true).         |
| `.onAgentStart(cb)`          | `(name: string) => void`                          | Applied to all registered agents.                      |
| `.onAgentError(cb)`          | `(name: string, error: Error) => void`            | Applied to all registered agents.                      |
| `.onToolCallStart(cb)`       | `(agentName, toolName, input) => void`            | Applied to all registered agents.                      |
| `.onToolCallEnd(cb)`         | `(agentName, toolName, output) => void`           | Applied to all registered agents.                      |
| `.onToolCallError(cb)`       | `(agentName, toolName, error) => void`            | Applied to all registered agents.                      |
| `.onMCPStart(cb)`            | `(agentName, mcpName) => void`                    | Applied to all registered agents.                      |
| `.onMCPError(cb)`            | `(agentName, mcpName, error) => void`             | Applied to all registered agents.                      |
| `.build()`                   | `() => IgniterAgentManagerCore`                   | Builds the manager.                                    |

### Built Manager Methods

| Method                   | Signature                                   | Description                                 |
| ------------------------ | ------------------------------------------- | ------------------------------------------- |
| `.register(name, agent)` | `(name: string, agent: BuiltAgent) => this` | Registers an agent (chainable).             |
| `.unregister(name)`      | `(name: string) => boolean`                 | Unregisters an agent.                       |
| `.has(name)`             | `(name: string) => boolean`                 | Checks if an agent is registered.           |
| `.get(name)`             | `(name: string) => BuiltAgent`              | Gets an agent by name. Throws if not found. |
| `.start(name)`           | `(name: string) => Promise<BuiltAgent>`     | Starts a single agent.                      |
| `.startAll()`            | `() => Promise<Map<string, Record>>`        | Starts all agents in parallel.              |
| `.getNames()`            | `() => string[]`                            | Returns registered agent names.             |
| `.getStatus()`           | `() => IgniterAgentInfo[]`                  | Returns status for all agents.              |
| `.getFailedAgents()`     | `() => IgniterAgentInfo[]`                  | Returns agents in error state.              |

***

## IgniterAgentTool

Creates individual tool definitions.

### `IgniterAgentTool.create(name)`

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `name`    | `string` | Yes      | Unique tool name within a toolset |

### Builder Methods

| Method                   | Required | Description                                |
| ------------------------ | -------- | ------------------------------------------ |
| `.withDescription(text)` | Yes      | Human-readable description shown to the AI |
| `.withInput(zodSchema)`  | Yes      | Zod schema defining input parameters       |
| `.withOutput(zodSchema)` | No       | Zod schema for output validation           |
| `.withExecute(handler)`  | Yes      | Async function performing the tool's logic |
| `.build()`               | Yes      | Returns the built tool definition          |

### Execute Handler

```typescript
type ExecuteHandler<TInput, TOutput> = (
  params: TInput,
  options: IgniterAgentToolExecuteOptions
) => Promise<TOutput>

interface IgniterAgentToolExecuteOptions {
  toolCallId: string
  messages: ModelMessage[]
  abortSignal?: AbortSignal
}
```

### Built Tool Properties

| Property       | Type                      | Description             |                          |
| -------------- | ------------------------- | ----------------------- | ------------------------ |
| `name`         | `string`                  | Tool name               |                          |
| `description`  | `string`                  | Tool description        |                          |
| `inputSchema`  | `ZodSchema`               | Input validation schema |                          |
| `outputSchema` | \`ZodSchema               | undefined\`             | Output validation schema |
| `execute`      | `Function`                | The execution handler   |                          |
| `$Infer`       | `{ Name, Input, Output }` | Type inference helper   |                          |

***

## IgniterAgentToolset

Groups related tools into a named collection.

### `IgniterAgentToolset.create(name)`

| Parameter | Type     | Required | Description                                         |
| --------- | -------- | -------- | --------------------------------------------------- |
| `name`    | `string` | Yes      | Unique toolset name (used as prefix for tool names) |

### Builder Methods

| Method            | Description                      |
| ----------------- | -------------------------------- |
| `.withName(name)` | Renames the toolset              |
| `.addTool(tool)`  | Adds a built tool to the toolset |
| `.build()`        | Returns the built toolset        |
| `.getName()`      | Returns the toolset name         |
| `.getTools()`     | Returns the tools object         |
| `.getToolCount()` | Returns the number of tools      |

### Built Toolset Properties

| Property  | Type              | Description                               |
| --------- | ----------------- | ----------------------------------------- |
| `name`    | `string`          | Toolset name                              |
| `type`    | `'custom'`        | Always 'custom' for user-defined toolsets |
| `status`  | `'connected'`     | Always 'connected' for custom toolsets    |
| `tools`   | `ToolSet`         | The tools collection                      |
| `toolset` | `ToolSet`         | Raw tools reference                       |
| `$Infer`  | `{ Name, Tools }` | Type inference helper                     |

***

## IgniterAgentMCPClient

Configures connections to MCP servers.

### `IgniterAgentMCPClient.create(name)`

| Parameter | Type     | Required | Description                   |
| --------- | -------- | -------- | ----------------------------- |
| `name`    | `string` | Yes      | Unique MCP configuration name |

### Common Methods

| Method              | Description                  |                                |
| ------------------- | ---------------------------- | ------------------------------ |
| \`.withType('stdio' | 'http')\`                    | Sets transport type (required) |
| `.withName(name)`   | Renames the configuration    |                                |
| `.build()`          | Returns the built MCP config |                                |

### Stdio-Specific Methods (after `withType('stdio')`)

| Method              | Description                              |
| ------------------- | ---------------------------------------- |
| `.withCommand(cmd)` | Command to execute (e.g., `npx`, `node`) |
| `.withArgs(args)`   | Command-line arguments array             |
| `.withEnv(env)`     | Environment variables record             |

### HTTP-Specific Methods (after `withType('http')`)

| Method                  | Description             |
| ----------------------- | ----------------------- |
| `.withURL(url)`         | MCP server endpoint URL |
| `.withHeaders(headers)` | HTTP headers record     |

### Built MCP Config Properties

| Property  | Type                                  | Description           |                |
| --------- | ------------------------------------- | --------------------- | -------------- |
| `name`    | `string`                              | Configuration name    |                |
| `type`    | \`'stdio'                             | 'http'\`              | Transport type |
| `command` | `string` (stdio only)                 | Executable command    |                |
| `args`    | `string[]` (stdio only)               | Command arguments     |                |
| `env`     | `Record<string, string>` (stdio only) | Environment variables |                |
| `url`     | `string` (http only)                  | Server URL            |                |
| `headers` | `Record<string, string>` (http only)  | HTTP headers          |                |

***

## IgniterAgentPrompt

Creates template-based system prompts.

### `IgniterAgentPrompt.create(template)`

| Parameter  | Type     | Required | Description                                      |
| ---------- | -------- | -------- | ------------------------------------------------ |
| `template` | `string` | Yes      | Template string with `{{variable}}` placeholders |

### Methods

| Method                      | Description                        |
| --------------------------- | ---------------------------------- |
| `.build(context)`           | Renders template with context data |
| `.addAppended(key, prompt)` | Appends another prompt or string   |
| `.removeAppended(key)`      | Removes an appended prompt         |
| `.getAppended()`            | Returns appended prompts object    |
| `.getTemplate()`            | Returns raw template string        |

***

## Adapters

### IgniterAgentInMemoryAdapter

```typescript
import { IgniterAgentInMemoryAdapter } from '@igniter-js/agents'

const adapter = IgniterAgentInMemoryAdapter.create({
  namespace: 'myapp',    // Namespace prefix for keys
  maxMessages: 1000,     // Max messages per chat
  maxChats: 100,         // Max chat sessions
})
```

| Method                           | Description                     |
| -------------------------------- | ------------------------------- |
| `.create(options)`               | Factory method                  |
| `.connect()`                     | No-op (interface compatibility) |
| `.disconnect()`                  | No-op (interface compatibility) |
| `.isConnected()`                 | Always returns `true`           |
| `.clear()`                       | Clears all stored data          |
| `getWorkingMemory(params)`       | Retrieves scoped working memory |
| `updateWorkingMemory(params)`    | Updates scoped working memory   |
| `saveMessage(message)`           | Saves a conversation message    |
| `getMessages(params)`            | Gets messages for a chat        |
| `saveChat(chat)`                 | Saves/updates a chat session    |
| `getChats(params)`               | Lists chat sessions             |
| `getChat(chatId)`                | Gets a single chat              |
| `updateChatTitle(chatId, title)` | Updates chat title              |
| `deleteChat(chatId)`             | Deletes a chat and its messages |

### IgniterAgentJSONFileAdapter

```typescript
import { IgniterAgentJSONFileAdapter } from '@igniter-js/agents'

const adapter = IgniterAgentJSONFileAdapter.create({
  filePath: './data/agent-memory.json',
  namespace: 'prod',
})
```

Same interface as InMemoryAdapter. Data persists to disk.

***

## Memory Configuration

### `IgniterAgentMemoryConfig`

```typescript
interface IgniterAgentMemoryConfig {
  provider: IgniterAgentMemoryProvider   // Adapter instance
  working?: {
    enabled: boolean                      // Enable working memory
    scope: string                         // Scope key (e.g., 'chat')
  }
  history?: {
    enabled: boolean                      // Enable chat history
    limit: number                         // Max messages per chat
  }
  chats?: {
    enabled: boolean                      // Enable chat sessions
  }
}
```

***

## Error Codes

### `IgniterAgentErrorCode`

| Code                           | Value                                     | Description               |
| ------------------------------ | ----------------------------------------- | ------------------------- |
| `UNKNOWN`                      | `IGNITER_AGENT_UNKNOWN_ERROR`             | Generic/unknown error     |
| `INVALID_CONFIG`               | `IGNITER_AGENT_INVALID_CONFIG`            | Invalid configuration     |
| `MISSING_REQUIRED`             | `IGNITER_AGENT_MISSING_REQUIRED`          | Required value missing    |
| `AGENT_NOT_INITIALIZED`        | `IGNITER_AGENT_NOT_INITIALIZED`           | Agent not initialized     |
| `AGENT_MODEL_MISSING`          | `IGNITER_AGENT_MODEL_MISSING`             | Model not configured      |
| `AGENT_BUILD_FAILED`           | `IGNITER_AGENT_BUILD_FAILED`              | Agent build failed        |
| `MCP_CONNECTION_FAILED`        | `IGNITER_AGENT_MCP_CONNECTION_FAILED`     | MCP connection failed     |
| `MCP_CLIENT_NOT_FOUND`         | `IGNITER_AGENT_MCP_CLIENT_NOT_FOUND`      | MCP client not found      |
| `MCP_TOOL_ERROR`               | `IGNITER_AGENT_MCP_TOOL_ERROR`            | MCP tool execution failed |
| `MCP_INVALID_CONFIG`           | `IGNITER_AGENT_MCP_INVALID_CONFIG`        | Invalid MCP configuration |
| `TOOL_EXECUTION_FAILED`        | `IGNITER_AGENT_TOOL_EXECUTION_FAILED`     | Tool execution failed     |
| `TOOL_NOT_FOUND`               | `IGNITER_AGENT_TOOL_NOT_FOUND`            | Tool not found            |
| `TOOL_VALIDATION_FAILED`       | `IGNITER_AGENT_TOOL_VALIDATION_FAILED`    | Tool validation failed    |
| `AGENT_CONTEXT_SCHEMA_INVALID` | `IGNITER_AGENT_CONTEXT_SCHEMA_INVALID`    | Invalid context schema    |
| `MEMORY_PROVIDER_ERROR`        | `IGNITER_AGENT_MEMORY_PROVIDER_ERROR`     | Memory provider error     |
| `MEMORY_NOT_FOUND`             | `IGNITER_AGENT_MEMORY_NOT_FOUND`          | Memory not found          |
| `MEMORY_UPDATE_FAILED`         | `IGNITER_AGENT_MEMORY_UPDATE_FAILED`      | Memory update failed      |
| `ADAPTER_CONNECTION_FAILED`    | `IGNITER_AGENT_ADAPTER_CONNECTION_FAILED` | Adapter connection failed |
| `ADAPTER_OPERATION_FAILED`     | `IGNITER_AGENT_ADAPTER_OPERATION_FAILED`  | Adapter operation failed  |
| `ADAPTER_NOT_INITIALIZED`      | `IGNITER_AGENT_ADAPTER_NOT_INITIALIZED`   | Adapter not initialized   |

### Error Classes

| Class                      | Extends             | Description              |
| -------------------------- | ------------------- | ------------------------ |
| `IgniterAgentError`        | `IgniterError`      | Base error class         |
| `IgniterAgentConfigError`  | `IgniterAgentError` | Configuration errors     |
| `IgniterAgentMCPError`     | `IgniterAgentError` | MCP operation errors     |
| `IgniterAgentToolError`    | `IgniterAgentError` | Tool execution errors    |
| `IgniterAgentMemoryError`  | `IgniterAgentError` | Memory operation errors  |
| `IgniterAgentAdapterError` | `IgniterAgentError` | Adapter operation errors |

### Type Guards

| Function                         | Signature                                            | Description                             |
| -------------------------------- | ---------------------------------------------------- | --------------------------------------- |
| `isIgniterAgentError(error)`     | `(error: unknown) => error is IgniterAgentError`     | Checks if error is an IgniterAgentError |
| `isIgniterAgentMCPError(error)`  | `(error: unknown) => error is IgniterAgentMCPError`  | Checks if error is an MCP error         |
| `isIgniterAgentToolError(error)` | `(error: unknown) => error is IgniterAgentToolError` | Checks if error is a tool error         |

***

## Type Exports

### `IgniterAgentHooks`

```typescript
interface IgniterAgentHooks {
  onAgentStart?: (name: string) => void
  onAgentError?: (name: string, error: Error) => void
  onToolCallStart?: (agentName: string, toolName: string, input: unknown) => void
  onToolCallEnd?: (agentName: string, toolName: string, output: unknown) => void
  onToolCallError?: (agentName: string, toolName: string, error: Error) => void
  onMCPStart?: (agentName: string, mcpName: string) => void
  onMCPError?: (agentName: string, mcpName: string, error: Error) => void
}
```

### `IgniterAgentBuiltAgent`

The type returned by `agent.build()`:

```typescript
type IgniterAgentBuiltAgent<
  TContextSchema = ZodSchema,
  TToolsets = Record<string, IgniterAgentToolset>,
  TModel = LanguageModel,
  TInstructions = IgniterAgentPromptTemplate,
>
```

### `IgniterAgentBuiltTool`

The type returned by `tool.build()`:

```typescript
type IgniterAgentBuiltTool<
  TName = string,
  TInput = unknown,
  TOutput = unknown,
>
```

### `IgniterAgentBuiltToolset`

The type returned by `toolset.build()`:

```typescript
type IgniterAgentBuiltToolset<
  TName = string,
  TTools = ToolSet,
>
```


---

# Best Practices

> Production-ready patterns for agent design, tool implementation, memory management, MCP configuration, and multi-agent orchestration.
URL: https://igniterjs.com/docs/agents/best-practices

## Best Practices

Guidelines for building production-grade agents with `@igniter-js/agents`.

***

## Agent Design

### ✅ Do: Create focused, single-purpose agents

```typescript
// Good: Each agent has a clear domain
const supportBot = IgniterAgent.create('support')
  .withPrompt(IgniterAgentPrompt.create('You are customer support.'))
  .addToolset(supportToolset)
  .build()

const codeBot = IgniterAgent.create('code')
  .withPrompt(IgniterAgentPrompt.create('You are a code assistant.'))
  .addToolset(codeToolset)
  .build()
```

### ❌ Don't: Overload a single agent with too many responsibilities

```typescript
// Bad: One agent trying to do everything
const megaBot = IgniterAgent.create('everything')
  .addToolset(supportToolset)
  .addToolset(codeToolset)
  .addToolset(analyticsToolset)
  .addToolset(devopsToolset)
  .addToolset(salesToolset)
  .build()
// → Slow, confused, expensive
```

### ✅ Do: Set clear context schemas

```typescript
const agent = IgniterAgent.create('typed')
  .withContextSchema(
    z.object({
      userId: z.string(),
      userRole: z.enum(['admin', 'user']),
      tenantId: z.string(),
    })
  )
  .build()
```

### ❌ Don't: Skip context schemas in production

```typescript
// Bad: Untyped context opens the door to runtime errors
const agent = IgniterAgent.create('untyped').build()

await agent.generate({
  chatId: 'x',
  userId: 'x',
  context: { usrRole: 'admin' }, // Typo caught zero times
  message: { role: 'user', content: '...' },
})
```

***

## Tool Design

### ✅ Do: Write specific, actionable descriptions

```typescript
// Good: The AI knows exactly when to use this
IgniterAgentTool.create('get_order')
  .withDescription(
    'Retrieve order details by order ID. Use this when a customer asks about their order status, delivery, or items.'
  )
```

### ❌ Don't: Write vague descriptions

```typescript
// Bad: The AI won't know when to call this
IgniterAgentTool.create('get_order')
  .withDescription('Gets stuff')
```

### ✅ Do: Validate inputs with Zod

```typescript
// Good: Compile-time and runtime safety
.withInput(
  z.object({
    orderId: z.string().min(1).describe('Order ID in format ORD-XXXX'),
    includeItems: z.boolean().default(true),
  })
)
```

### ❌ Don't: Use `z.any()` or `z.unknown()` for inputs

```typescript
// Bad: No type safety
.withInput(z.any())
```

### ✅ Do: Return structured data from tools

```typescript
// Good: Predictable, typed output
.withExecute(async ({ orderId }) => {
  return {
    found: true,
    orderId,
    status: 'shipped',
    items: [{ name: 'Widget', qty: 2 }],
  }
})
```

### ❌ Don't: Return raw API responses directly

```typescript
// Bad: The AI gets an opaque blob
.withExecute(async ({ orderId }) => {
  return api.get(`/orders/${orderId}`) // Returns raw HTTP response
})
```

***

## Memory Management

### ✅ Do: Enable memory for multi-turn conversations

```typescript
const agent = IgniterAgent.create('bot')
  .withMemory({
    provider: adapter,
    working: { enabled: true, scope: 'chat' },
    history: { enabled: true, limit: 100 },
    chats: { enabled: true },
  })
  .build()
```

### ❌ Don't: Use in-memory adapter in production

```typescript
// Bad: Lost on restart
const memory = IgniterAgentInMemoryAdapter.create({ namespace: 'prod' })
```

### ✅ Do: Build a persistent adapter for production

```typescript
// Redis, PostgreSQL, or file-based for production
const memory = new RedisMemoryAdapter(redis)
```

***

## MCP Configuration

### ✅ Do: Handle MCP connection errors gracefully

```typescript
const agent = IgniterAgent.create('bot')
  .addMCP(filesystemMCP)
  .onMCPError((agent, mcp, err) => {
    logger.warn(`MCP '${mcp}' unavailable: ${err.message}`)
    // Continue with reduced capabilities
  })
  .build()
```

### ❌ Don't: Ignore MCP connection failures

```typescript
// Bad: Unhandled MCP error crashes the agent
await agent.start() // throws if MCP unreachable
```

### ✅ Do: Use environment variables for sensitive MCP config

```typescript
.withEnv({
  API_KEY: process.env.MCP_API_KEY!,
  // Never hardcode secrets
})
```

### ❌ Don't: Hardcode credentials in MCP config

```typescript
// Bad: Committed to source control
.withEnv({
  API_KEY: 'sk-prod-abc123',
})
```

***

## Observability

### ✅ Do: Instrument with hooks and telemetry

```typescript
const agent = IgniterAgent.create('bot')
  .withTelemetry(telemetry)
  .onAgentError((name, err) => alerting.error(err))
  .onToolCallError((agent, tool, err) => metrics.increment('tool.errors'))
  .build()
```

### ❌ Don't: Run agents in production without observability

```typescript
// Bad: Silent failures, no audit trail
const agent = IgniterAgent.create('bot').withModel(openai('gpt-4o')).build()
```

***

## Multi-Agent Patterns

### ✅ Do: Use the manager for shared resources

```typescript
const manager = IgniterAgentManager.create()
  .withTelemetry(sharedTelemetry)
  .withLogger(sharedLogger)
  .addAgent('support', supportBot)
  .addAgent('sales', salesBot)
  .build()
```

### ❌ Don't: Duplicate telemetry/logger per agent

```typescript
// Bad: Redundant configuration
const supportBot = IgniterAgent.create('support')
  .withTelemetry(t1)
  .withLogger(l1)
  .build()
const salesBot = IgniterAgent.create('sales')
  .withTelemetry(t2)
  .withLogger(l2)
  .build()
```

### ✅ Do: Set `continueOnError: true` for resilient multi-agent systems

```typescript
const manager = IgniterAgentManager.create()
  .withContinueOnError(true) // One failing agent won't crash the others
  .build()
```

***

## Performance

### ✅ Do: Reuse agent instances

```typescript
// Good: Create once, use many times
const agent = IgniterAgent.create('bot').withModel(openai('gpt-4o')).build()
await agent.start()

for (const message of messages) {
  await agent.generate({ chatId, userId, context, message })
}
```

### ❌ Don't: Create new agents per request

```typescript
// Bad: Expensive — MCP reconnection on every request
async function handle(msg) {
  const agent = IgniterAgent.create('bot')...build()
  await agent.start()
  return agent.generate(...)
}
```

### ✅ Do: Use `gpt-4o-mini` for development and `gpt-4o` for production

### ✅ Do: Limit message history to reduce token costs

```typescript
const memoryConfig = {
  history: { enabled: true, limit: 20 }, // Keep last 20 messages
}
```


---

# Building Agents

> Complete guide to the IgniterAgent builder API. Model selection, prompt configuration, context schemas, lifecycle hooks, memory, and MCP integration.
URL: https://igniterjs.com/docs/agents/building-agents

## Building Agents

The `IgniterAgent` builder is the primary entry point for creating AI agents. It provides a type-safe, immutable fluent API that infers the full agent configuration at compile time.

***

## The Builder Pattern

Every agent starts with `IgniterAgent.create()` and ends with `.build()`. In between, you chain configuration methods — each returning a **new builder instance** with updated type parameters.

```typescript
import { IgniterAgent } from '@igniter-js/agents'
import { openai } from '@ai-sdk/openai'

const agent = IgniterAgent
  .create('my-agent')          // IgniterAgentBuilder<'my-agent', ...>
  .withModel(openai('gpt-4'))  // ...<..., LanguageModel, ...>
  .build()                     // IgniterAgentBuiltAgent
```

<Callout type="info">
  The builder is **immutable** — every method call creates a new builder instance. This means you can fork configurations from a base builder safely.
</Callout>

***

## Agent Configuration

### Model Selection

Choose any model provider compatible with the Vercel AI SDK:

```typescript
import { openai } from '@ai-sdk/openai'
import { anthropic } from '@ai-sdk/anthropic'
import { google } from '@ai-sdk/google'

// OpenAI
const gptAgent = IgniterAgent.create('gpt').withModel(openai('gpt-4o')).build()

// Anthropic
const claudeAgent = IgniterAgent.create('claude').withModel(anthropic('claude-3-5-sonnet-latest')).build()

// Google
const geminiAgent = IgniterAgent.create('gemini').withModel(google('gemini-2.0-flash')).build()
```

### Prompt Instructions

Set the agent's system prompt using `IgniterAgentPrompt`:

```typescript
import { IgniterAgent, IgniterAgentPrompt } from '@igniter-js/agents'

const agent = IgniterAgent
  .create('assistant')
  .withModel(openai('gpt-4o'))
  .withPrompt(
    IgniterAgentPrompt.create(`
      You are a helpful coding assistant.
      - Always provide type-safe TypeScript
      - Include JSDoc comments
      - Follow the project's ESLint rules
    `)
  )
  .build()
```

Prompts support `{{variable}}` interpolation using context data passed at generation time. See [Prompts](/docs/agents/prompts) for full details.

### Context Schema

Define a Zod schema for type-safe context passed to each `.generate()` call:

```typescript
import { z } from 'zod'

const contextSchema = z.object({
  userId: z.string(),
  userRole: z.enum(['admin', 'user', 'guest']),
  preferences: z.object({
    language: z.string().default('en'),
    theme: z.string().optional(),
  }),
})

const agent = IgniterAgent
  .create('typed-bot')
  .withModel(openai('gpt-4o'))
  .withContextSchema(contextSchema)
  .build()

// Context is fully type-checked
await agent.generate({
  chatId: 'chat_001',
  userId: 'user_001',
  context: {
    userRole: 'admin',          // ✅ Must be 'admin' | 'user' | 'guest'
    preferences: { language: 'pt' },
  },
  message: { role: 'user', content: 'Hello!' },
})
```

<Callout type="warn">
  If you set a context schema, the `context` field in `.generate()` and `.stream()` becomes required and type-checked against the schema. Context data is also available in prompt templates via `{{variable}}`.
</Callout>

***

## Adding Tools

### Custom Toolsets

Tools defined with `IgniterAgentTool` and grouped with `IgniterAgentToolset`:

```typescript
import { IgniterAgentTool, IgniterAgentToolset } from '@igniter-js/agents'
import { z } from 'zod'

const searchTool = IgniterAgentTool
  .create('search_docs')
  .withDescription('Search the documentation')
  .withInput(z.object({ query: z.string() }))
  .withExecute(async ({ query }) => {
    // Search your docs here
    return { results: ['Result 1', 'Result 2'] }
  })
  .build()

const docsToolset = IgniterAgentToolset
  .create('docs')
  .addTool(searchTool)
  .build()

const agent = IgniterAgent
  .create('docs-bot')
  .withModel(openai('gpt-4o'))
  .addToolset(docsToolset)
  .build()
```

See [Tools & Toolsets](/docs/agents/tools-toolsets) for the complete tool builder API.

### MCP Clients

Connect to external MCP servers for tools discovered at runtime:

```typescript
import { IgniterAgentMCPClient } from '@igniter-js/agents'

const filesystemMCP = IgniterAgentMCPClient
  .create('filesystem')
  .withType('stdio')
  .withCommand('npx')
  .withArgs(['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])
  .build()

const agent = IgniterAgent
  .create('mcp-agent')
  .withModel(openai('gpt-4o'))
  .addMCP(filesystemMCP)
  .build()
```

See [MCP Integration](/docs/agents/mcp-integration) for full transport configuration.

***

## Memory Configuration

Persistent memory enables agents to remember conversations across turns:

```typescript
import { IgniterAgentInMemoryAdapter } from '@igniter-js/agents'

const adapter = IgniterAgentInMemoryAdapter.create({ namespace: 'app' })

const memoryConfig = {
  provider: adapter,
  working: { enabled: true, scope: 'chat' },
  history: { enabled: true, limit: 100 },
  chats: { enabled: true },
}

const agent = IgniterAgent
  .create('memory-bot')
  .withModel(openai('gpt-4o'))
  .withMemory(memoryConfig)
  .build()
```

See [Memory System](/docs/agents/memory) for adapter options and custom implementations.

***

## Observability

### Logger

Attach an `IgniterLogger` instance for structured logs:

```typescript
import { IgniterLogger } from '@igniter-js/common'

const agent = IgniterAgent
  .create('logged-bot')
  .withModel(openai('gpt-4o'))
  .withLogger(myLogger)
  .build()
```

### Telemetry

Attach an `IgniterTelemetryManager` for structured observability events:

```typescript
import { IgniterTelemetry } from '@igniter-js/telemetry'

const telemetry = IgniterTelemetry.create().build()

const agent = IgniterAgent
  .create('observed-bot')
  .withModel(openai('gpt-4o'))
  .withTelemetry(telemetry)
  .build()
```

### Lifecycle Hooks

Subscribe to agent and tool events directly on the builder:

```typescript
const agent = IgniterAgent
  .create('hooked-bot')
  .withModel(openai('gpt-4o'))
  .onAgentStart((name) => console.log(`${name} started`))
  .onAgentError((name, error) => console.error(`${name} failed:`, error))
  .onToolCallStart((agentName, tool, input) => console.log(`[${agentName}] → ${tool}`))
  .onToolCallEnd((agentName, tool, output) => console.log(`[${agentName}] ← ${tool}`))
  .onToolCallError((agentName, tool, error) => console.error(`[${agentName}] ✕ ${tool}`, error))
  .onMCPStart((agentName, mcp) => console.log(`${agentName}: connecting MCP ${mcp}`))
  .onMCPError((agentName, mcp, error) => console.error(`${agentName}: MCP ${mcp} failed`, error))
  .build()
```

See [Hooks & Telemetry](/docs/agents/hooks-telemetry) for the complete event model.

***

## Agent Lifecycle

### The Agent Runtime

Once built, the agent exposes these methods:

| Method                    | Description                                                                   |
| ------------------------- | ----------------------------------------------------------------------------- |
| `agent.start()`           | Initializes MCP connections. Must be called before `generate()` or `stream()` |
| `agent.stop()`            | Disconnects MCP connections gracefully                                        |
| `agent.generate(options)` | Generates a single response (non-streaming)                                   |
| `agent.stream(options)`   | Streams a response token-by-token                                             |
| `agent.getName()`         | Returns the agent's configured name                                           |
| `agent.getConfig()`       | Returns the full configuration object                                         |
| `agent.getToolsets()`     | Returns the configured toolsets (including MCP)                               |

### Generate vs Stream

```typescript
// Single response
const result = await agent.generate({
  chatId: 'chat_001',
  userId: 'user_001',
  context: {},
  message: { role: 'user', content: 'Hello!' },
})

console.log(result.content)        // Full response text
console.log(result.toolCalls)      // Tools the agent called
console.log(result.toolResults)    // Results from tool calls
console.log(result.finishReason)   // Why generation stopped

// Streaming response
const stream = await agent.stream({
  chatId: 'chat_001',
  userId: 'user_001',
  context: {},
  message: { role: 'user', content: 'Tell me a story' },
})

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}
```

### Generate Options

```typescript
interface IgniterAgentGenerateOptions {
  chatId: string              // Unique conversation identifier
  userId: string              // User identifier for memory scoping
  context: Record<string, unknown> // Context data (typed if schema set)
  message: {                  // Single message or...
    role: 'user' | 'assistant'
    content: string
  }
  messages?: ModelMessage[]   // ...OR multiple messages
}
```

***

## Complete Example

A fully-configured agent with tools, memory, hooks, and telemetry:

```typescript
import {
  IgniterAgent,
  IgniterAgentTool,
  IgniterAgentToolset,
  IgniterAgentPrompt,
  IgniterAgentInMemoryAdapter,
} from '@igniter-js/agents'
import { openai } from '@ai-sdk/openai'
import { z } from 'zod'
import { IgniterTelemetry } from '@igniter-js/telemetry'

// Tools
const getTasks = IgniterAgentTool
  .create('get_tasks')
  .withDescription('Get tasks for today')
  .withInput(z.object({ priority: z.enum(['high', 'medium', 'low']).optional() }))
  .withExecute(async ({ priority }) => {
    return [
      { id: 1, title: 'Review PR', priority: 'high' },
      { id: 2, title: 'Update docs', priority: 'medium' },
    ]
  })
  .build()

const taskToolset = IgniterAgentToolset
  .create('tasks')
  .addTool(getTasks)
  .build()

// Memory
const memoryAdapter = IgniterAgentInMemoryAdapter.create({ namespace: 'prod' })

// Telemetry
const telemetry = IgniterTelemetry.create().build()

// Agent
const agent = IgniterAgent
  .create('productivity-bot')
  .withModel(openai('gpt-4o'))
  .withPrompt(IgniterAgentPrompt.create('You are a productivity assistant.'))
  .withContextSchema(z.object({ userId: z.string() }))
  .addToolset(taskToolset)
  .withMemory({
    provider: memoryAdapter,
    working: { enabled: true, scope: 'chat' },
    history: { enabled: true, limit: 100 },
    chats: { enabled: true },
  })
  .withTelemetry(telemetry)
  .onAgentStart((name) => console.log(`${name} is live`))
  .onToolCallStart((agent, tool, input) => console.log(`🔧 ${tool} called`))
  .build()

await agent.start()

const result = await agent.generate({
  chatId: 'chat_001',
  userId: 'user_001',
  context: { userId: 'user_001' },
  message: { role: 'user', content: 'What do I need to do today?' },
})

console.log(result.content)
```


---

# Hooks & Telemetry

> Monitor agent operations with lifecycle hooks and structured telemetry events. Agent start/error, tool execution, MCP connections, and memory operations.
URL: https://igniterjs.com/docs/agents/hooks-telemetry

## Hooks & Telemetry

Agents provide two complementary observability mechanisms: **lifecycle hooks** for inline callbacks and **telemetry events** for structured, production-grade monitoring.

***

## Lifecycle Hooks

Hooks give you direct callbacks on key agent events. Configure them on the agent or manager builder.

### Available Hooks

| Hook              | Signature                                                        | When it fires                                    |
| ----------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
| `onAgentStart`    | `(name: string) => void`                                         | Agent starts successfully                        |
| `onAgentError`    | `(name: string, error: Error) => void`                           | Agent fails to start or encounters a fatal error |
| `onToolCallStart` | `(agentName: string, toolName: string, input: unknown) => void`  | Before a tool executes                           |
| `onToolCallEnd`   | `(agentName: string, toolName: string, output: unknown) => void` | After a tool completes successfully              |
| `onToolCallError` | `(agentName: string, toolName: string, error: Error) => void`    | When a tool execution fails                      |
| `onMCPStart`      | `(agentName: string, mcpName: string) => void`                   | Before connecting to an MCP server               |
| `onMCPError`      | `(agentName: string, mcpName: string, error: Error) => void`     | When an MCP connection fails                     |

### Configuring Hooks

On a single agent:

```typescript
const agent = IgniterAgent
  .create('bot')
  .withModel(openai('gpt-4o'))
  .onAgentStart((name) => console.log(`${name} is live`))
  .onAgentError((name, err) => console.error(`${name} crashed:`, err))
  .onToolCallStart((agent, tool, input) => {
    console.log(`[${agent}] Calling ${tool} with:`, input)
  })
  .onToolCallEnd((agent, tool, output) => {
    console.log(`[${agent}] ${tool} returned:`, output)
  })
  .onToolCallError((agent, tool, err) => {
    console.error(`[${agent}] ${tool} failed:`, err.message)
  })
  .onMCPStart((agent, mcp) => console.log(`${agent}: connecting MCP '${mcp}'`))
  .onMCPError((agent, mcp, err) => {
    console.error(`${agent}: MCP '${mcp}' failed:`, err.message)
  })
  .build()
```

On a manager (applied to all registered agents):

```typescript
const manager = IgniterAgentManager
  .create()
  .onToolCallStart((agentName, tool, input) => {
    // Track tool usage across all agents
    metrics.increment('tool_calls', { agent: agentName, tool })
  })
  .onToolCallEnd((agentName, tool, output) => {
    metrics.timing('tool_duration', { agent: agentName, tool })
  })
  .build()
```

### Runtime Hook Attachment

Hooks can also be attached after building via `attachHooks()`:

```typescript
const agent = IgniterAgent.create('bot').withModel(openai('gpt-4o')).build()

agent.attachHooks({
  onAgentStart: (name) => console.log(`Started: ${name}`),
  onToolCallStart: (agentName, tool) => console.log(`Tool: ${tool}`),
})
```

<Callout type="info">
  When using a manager, hooks set on the manager are **merged** with any hooks already set on individual agents. Both will fire.
</Callout>

***

## Telemetry Integration

For production-grade observability, use `@igniter-js/telemetry` to emit structured events:

```typescript
import { IgniterTelemetry } from '@igniter-js/telemetry'

const telemetry = IgniterTelemetry.create().build()

const agent = IgniterAgent
  .create('bot')
  .withModel(openai('gpt-4o'))
  .withTelemetry(telemetry)
  .build()
```

### Telemetry Events

All events use the `igniter.agent.*` namespace:

#### Lifecycle Events

| Event                                   | Level | Key Attributes                                                           |
| --------------------------------------- | ----- | ------------------------------------------------------------------------ |
| `igniter.agent.lifecycle.start.started` | debug | `ctx.agent.name`, `ctx.lifecycle.toolsetCount`, `ctx.lifecycle.mcpCount` |
| `igniter.agent.lifecycle.start.success` | debug | + `ctx.lifecycle.durationMs`                                             |
| `igniter.agent.lifecycle.start.error`   | error | + `ctx.error.code`, `ctx.error.message`                                  |
| `igniter.agent.lifecycle.stop.started`  | debug | Same as start                                                            |
| `igniter.agent.lifecycle.stop.success`  | debug | + duration                                                               |
| `igniter.agent.lifecycle.stop.error`    | error | + error details                                                          |

#### MCP Events

| Event                                  | Key Attributes                              |
| -------------------------------------- | ------------------------------------------- |
| `igniter.agent.mcp.connect.started`    | `ctx.mcp.name`, `ctx.mcp.type`              |
| `igniter.agent.mcp.connect.success`    | + `ctx.mcp.toolCount`, `ctx.mcp.durationMs` |
| `igniter.agent.mcp.connect.error`      | + `ctx.error.*`                             |
| `igniter.agent.mcp.disconnect.started` | `ctx.mcp.name`, `ctx.mcp.type`              |
| `igniter.agent.mcp.disconnect.success` | + `ctx.mcp.durationMs`                      |
| `igniter.agent.mcp.disconnect.error`   | + `ctx.error.*`                             |

#### Memory Events

| Event                                    | Key Attributes                                |
| ---------------------------------------- | --------------------------------------------- |
| `igniter.agent.memory.operation.started` | `ctx.memory.operation`, `ctx.memory.scope`    |
| `igniter.agent.memory.operation.success` | + `ctx.memory.durationMs`, `ctx.memory.count` |
| `igniter.agent.memory.operation.error`   | + `ctx.error.code`, `ctx.error.message`       |

### Processing Telemetry Events

```typescript
import { IgniterTelemetry } from '@igniter-js/telemetry'

const telemetry = IgniterTelemetry
  .create()
  .onEvent('igniter.agent.lifecycle.start.error', (event) => {
    // Send to your alerting system
    alerting.send({
      severity: 'critical',
      message: `Agent ${event.attributes['ctx.agent.name']} failed to start`,
    })
  })
  .onEvent('igniter.agent.mcp.connect.error', (event) => {
    alerting.send({
      severity: 'warning',
      message: `MCP '${event.attributes['ctx.mcp.name']}' failed`,
    })
  })
  .onEvent('igniter.agent.memory.operation.error', (event) => {
    console.error(
      `Memory operation '${event.attributes['ctx.memory.operation']}' failed:`,
      event.attributes['ctx.error.message']
    )
  })
  .build()
```

***

## Logger Integration

Attach an `IgniterLogger` for structured debug/info/error logging:

```typescript
import { IgniterLogger } from '@igniter-js/common'

const agent = IgniterAgent
  .create('bot')
  .withModel(openai('gpt-4o'))
  .withLogger(myLogger)
  .build()

// The logger receives structured messages:
// debug: "IgniterAgent.start started" { agent: 'bot', toolsetCount: 2, mcpCount: 1 }
// success: "IgniterAgent.start success" { agent: 'bot', durationMs: 342 }
// error: "IgniterAgent.mcp.connect failed" Error(...)
```

When using a manager, loggers are automatically scoped with `logger.child('IgniterAgent', { agent: name })`:

```typescript
const manager = IgniterAgentManager
  .create()
  .withLogger(myLogger)     // Automatically scoped per agent
  .addAgent('support', supportAgent)
  .build()
```

***

## Choosing Hooks vs Telemetry

| Use Case                  | Hooks            | Telemetry           |
| ------------------------- | ---------------- | ------------------- |
| **Inline logging**        | ✅ Best           | Overkill            |
| **Custom side effects**   | ✅ Best           | Not designed for    |
| **Production monitoring** | No               | ✅ Best              |
| **Aggregated metrics**    | Manual           | ✅ Built-in          |
| **Alerting**              | Manual           | ✅ Structured events |
| **Debugging**             | ✅ Immediate      | ✅ Searchable        |
| **Performance**           | Minimal overhead | Optimized pipeline  |

<Callout type="info">
  You can use **both** — hooks for immediate reactions (logging, side effects) and telemetry for production monitoring (metrics, alerting, dashboards).
</Callout>


---

# Introduction

> Production-ready, type-safe AI agent framework for Igniter.js. Build intelligent agents with custom tools, persistent memory, telemetry, and multi-agent orchestration.
URL: https://igniterjs.com/docs/agents

## Overview

`@igniter-js/agents` is a **production-grade, type-safe** AI agent framework built on the [Vercel AI SDK](https://sdk.vercel.ai). It provides a fluent builder API for creating AI agents with custom tools, persistent memory, MCP integration, telemetry, and multi-agent orchestration — all with full TypeScript type inference.

Whether you're building a simple chatbot, a multi-agent customer support system, or an autonomous coding assistant, agents gives you the foundation with compile-time safety and production observability.

<Callout type="info">
  Agents is a **fully independent package** — use it in any Node.js or Bun application. No framework lock-in. Works with Express, Next.js, Fastify, Hono, or background workers.
</Callout>

### Key Features

* **Type-safe tooling** — Define tools with Zod schemas and get full type inference on inputs, outputs, and execution handlers
* **Fluent builder API** — Immutable, chainable configuration for agents, tools, toolsets, MCP clients, and prompts
* **Persistent memory** — Adapter-based storage for working memory, chat history, and chat sessions
* **MCP integration** — Native support for Model Context Protocol servers via stdio and HTTP transports
* **Multi-agent orchestration** — Manage multiple specialized agents with a single manager, shared telemetry, and hooks
* **Comprehensive telemetry** — Structured observability events for every lifecycle phase, tool call, MCP connection, and memory operation
* **Lifecycle hooks** — Subscribe to agent start/error, tool call start/end/error, and MCP connection events
* **Prompt templates** — Context-aware prompt building with `{{variable}}` interpolation and appended prompt support
* **Pluggable adapters** — In-memory and JSON file adapters included; build custom adapters for any storage backend
* **Predictable errors** — Stable error codes (`AGENT_NOT_INITIALIZED`, `MEMORY_PROVIDER_ERROR`, `INVALID_CONFIG`) for programmatic handling

***

## Architecture

Agents follows the **builder pattern** — every component is built through a fluent, chainable API. The agent core handles model interaction, tool execution, MCP lifecycle, memory persistence, telemetry, and hooks.

```
┌─────────────────────────────────────────────────────┐
│                  IgniterAgentManager                │
│  (multi-agent orchestration, shared telemetry)      │
├─────────────────────────────────────────────────────┤
│                  IgniterAgentCore                   │
│  (model interaction, tool exec, MCP lifecycle)      │
├──────────┬──────────┬──────────┬───────────────────┤
│  Tools   │ Toolsets │   MCP    │      Memory       │
│  (typed  │ (grouped │ (stdio,  │  (working, chat,  │
│   funcs) │  tools)  │  http)   │   history)        │
├──────────┴──────────┴──────────┴───────────────────┤
│          Prompt Templates (interpolation)           │
├─────────────────────────────────────────────────────┤
│     Telemetry + Logger + Hooks (observability)      │
└─────────────────────────────────────────────────────┘
```

Every operation flows through the same pipeline: **validate input → execute → capture telemetry → fire hooks → return result**.

### Mental Model

| Concept        | What it is                                 | Example                                                                  |
| -------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
| **Agent**      | AI-powered runtime with tools and memory   | `IgniterAgent.create('assistant').withModel(...).build()`                |
| **Tool**       | Typed, executable function the AI can call | `IgniterAgentTool.create('getWeather').withInput(z.object({...}))`       |
| **Toolset**    | Collection of related tools by domain      | `IgniterAgentToolset.create('github').addTool(...).addTool(...).build()` |
| **MCP Client** | Connection to external MCP servers         | `IgniterAgentMCPClient.create('filesystem').withType('stdio').build()`   |
| **Memory**     | Persistent storage for context and history | `{ provider: adapter, working: {...}, history: {...} }`                  |
| **Manager**    | Orchestrates multiple agents               | `IgniterAgentManager.create().addAgent('support', agent).build()`        |
| **Prompt**     | Template-based system instructions         | `IgniterAgentPrompt.create('You are {{role}}.')`                         |
| **Hooks**      | Lifecycle and tool execution callbacks     | `{ onAgentStart: ..., onToolCallStart: ... }`                            |

***

## Quick Look

Here's a complete agent with a custom tool, ready to run:

```typescript
import {
  IgniterAgent,
  IgniterAgentTool,
  IgniterAgentToolset,
  IgniterAgentPrompt,
} from '@igniter-js/agents'
import { openai } from '@ai-sdk/openai'
import { z } from 'zod'

// 1. Define a typed tool
const weatherTool = IgniterAgentTool
  .create('get_weather')
  .withDescription('Get current weather for a location')
  .withInput(
    z.object({
      location: z.string().describe('City name'),
      unit: z.enum(['C', 'F']).default('C'),
    })
  )
  .withExecute(async ({ location, unit }) => {
    // Call your weather API here
    return { location, temperature: 22, unit, condition: 'Sunny' }
  })
  .build()

// 2. Group tools into a toolset
const weatherToolset = IgniterAgentToolset
  .create('weather')
  .addTool(weatherTool)
  .build()

// 3. Create the agent
const agent = IgniterAgent
  .create('weather-bot')
  .withModel(openai('gpt-4'))
  .withPrompt(
    IgniterAgentPrompt.create(
      'You are a helpful weather assistant. Use tools to answer weather questions.'
    )
  )
  .addToolset(weatherToolset)
  .build()

// 4. Start and use
await agent.start()

const result = await agent.generate({
  chatId: 'chat_123',
  userId: 'user_456',
  context: {},
  message: {
    role: 'user',
    content: "What's the weather in London?",
  },
})

console.log(result.content)
```

**✅ That's it!** A fully type-safe agent with custom tools, ready for production.

***

## Package Tour

<Files>
  <Folder name="packages/agents/src" defaultOpen>
    <Folder name="builders">
      <File name="agent.builder.ts">
        Fluent API for building agents (model, tools, MCP, memory, hooks)
      </File>

      <File name="main.builder.ts">
        Manager builder for multi-agent orchestration
      </File>

      <File name="tool.builder.ts">
        Fluent API for single tool definitions
      </File>

      <File name="toolset.builder.ts">
        Fluent API for tool collections
      </File>

      <File name="mcp.builder.ts">
        Fluent API for MCP client configuration
      </File>

      <File name="prompt.builder.ts">
        Template interpolation with 

        {"{{variable}}"}

         support
      </File>
    </Folder>

    <Folder name="core">
      <File name="agent.ts">
        Agent runtime: generate, stream, MCP lifecycle, tool execution
      </File>

      <File name="manager.ts">
        Multi-agent orchestration: register, startAll, routing
      </File>

      <File name="memory.ts">
        Memory runtime wrapper with telemetry and error handling
      </File>
    </Folder>

    <Folder name="adapters">
      <File name="memory.adapter.ts">
        In-memory storage for development/testing
      </File>

      <File name="json-file.adapter.ts">
        JSON file persistence for single-machine deployments
      </File>
    </Folder>

    <Folder name="types">
      <File name="agent.ts">
        Core agent type definitions
      </File>

      <File name="builder.ts">
        Builder output types
      </File>

      <File name="memory.ts">
        Memory provider interface
      </File>

      <File name="hooks.ts">
        Lifecycle hook signatures
      </File>

      <File name="adapter.ts">
        Adapter configuration types
      </File>
    </Folder>

    <Folder name="errors">
      <File name="agent.error.ts">
        Stable error codes and error classes
      </File>
    </Folder>
  </Folder>
</Files>

***

## Next Steps

* [Installation](/docs/agents/installation) — All package managers, peer dependencies, and runtime requirements
* [Quick Start](/docs/agents/quick-start) — Three complete scenarios in under 5 minutes each
* [Building Agents](/docs/agents/building-agents) — Deep dive into the agent builder API
* [Tools & Toolsets](/docs/agents/tools-toolsets) — Type-safe tool creation and organization


---

# Installation

> Install @igniter-js/agents with any package manager. Peer dependencies, AI model provider setup, optional MCP support, and runtime requirements.
URL: https://igniterjs.com/docs/agents/installation

## Installation

### Core Package

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/agents ai zod
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/agents ai zod
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/agents ai zod
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/agents ai zod
    ```
  </Tab>
</Tabs>

### AI Model Provider (Required)

Choose and install at least one AI model provider. Agents works with any provider supported by the [Vercel AI SDK](https://sdk.vercel.ai/docs/models):

<Tabs items={['OpenAI', 'Anthropic', 'Google', 'Mistral']}>
  <Tab value="OpenAI">
    ```bash
    npm install @ai-sdk/openai
    ```

    Set your API key:

    ```bash
    export OPENAI_API_KEY="sk-..."
    ```
  </Tab>

  <Tab value="Anthropic">
    ```bash
    npm install @ai-sdk/anthropic
    ```

    ```bash
    export ANTHROPIC_API_KEY="sk-ant-..."
    ```
  </Tab>

  <Tab value="Google">
    ```bash
    npm install @ai-sdk/google
    ```

    ```bash
    export GOOGLE_GENERATIVE_AI_API_KEY="..."
    ```
  </Tab>

  <Tab value="Mistral">
    ```bash
    npm install @ai-sdk/mistral
    ```

    ```bash
    export MISTRAL_API_KEY="..."
    ```
  </Tab>
</Tabs>

<Callout type="info">
  You can also use **Ollama** for local models, **Groq**, **Cohere**, **DeepSeek**, or any other [AI SDK provider](https://sdk.vercel.ai/providers/ai-sdk-providers).
</Callout>

### Optional: MCP Support

To connect agents to external Model Context Protocol servers:

```bash
npm install @ai-sdk/mcp @modelcontextprotocol/sdk
```

### Optional: Telemetry

For production observability with structured events:

```bash
npm install @igniter-js/telemetry
```

***

## Peer Dependencies

| Package                       | Version | Required | Purpose                                         |
| ----------------------------- | ------- | -------- | ----------------------------------------------- |
| `ai`                          | `>=4.0` | ✅ Yes    | Core AI SDK for model interaction               |
| `zod`                         | `>=3.0` | ✅ Yes    | Runtime schema validation for tools and context |
| `@ai-sdk/openai` (or similar) | `>=1.0` | ✅ Yes    | AI model provider                               |
| `@igniter-js/telemetry`       | `*`     | No       | Structured telemetry events                     |
| `@ai-sdk/mcp`                 | `*`     | No       | MCP server integration                          |
| `@modelcontextprotocol/sdk`   | `*`     | No       | MCP client transport layer                      |

***

## Runtime Requirements

| Environment | Version         | Notes               |
| ----------- | --------------- | ------------------- |
| **Node.js** | `>= 22.0.0`     | Full support        |
| **Bun**     | `>= 1.0.0`      | Full support        |
| **Deno**    | `>= 1.30.0`     | Full support        |
| **Browser** | ❌ Not supported | Server-only package |

<Callout type="warn">
  Agents is **server-only**. Importing it in a browser environment will trigger the shim protection. Use it in API routes, server actions, background workers, or CLI tools.
</Callout>

***

## Verify Installation

After installing, verify everything is wired correctly:

```typescript
import {
  IgniterAgent,
  IgniterAgentTool,
  IgniterAgentToolset,
  IgniterAgentPrompt,
  IgniterAgentMCPClient,
  IgniterAgentManager,
  IgniterAgentInMemoryAdapter,
} from '@igniter-js/agents'
import { openai } from '@ai-sdk/openai'
import { z } from 'zod'

// Quick smoke test — should build without errors
const agent = IgniterAgent
  .create('test')
  .withModel(openai('gpt-4o-mini'))
  .withPrompt(IgniterAgentPrompt.create('You are a test agent.'))
  .build()

console.log('Agent name:', agent.getName())
// → Agent name: test
```

**✅ Success!** If you see the agent name printed, your installation is ready.

***

## Next Steps

* [Quick Start](/docs/agents/quick-start) — Build your first agent in under 5 minutes
* [Building Agents](/docs/agents/building-agents) — Deep dive into the agent builder API


---

# MCP Integration

> Connect agents to external tool providers via Model Context Protocol. Stdio and HTTP transports, environment variables, headers, and runtime tool discovery.
URL: https://igniterjs.com/docs/agents/mcp-integration

## MCP Integration

The **Model Context Protocol (MCP)** allows agents to discover and use tools from external servers at runtime. `@igniter-js/agents` supports both **stdio** (local process) and **HTTP** (remote server) transports.

***

## What is MCP?

MCP is an open protocol that standardizes how AI applications connect to external tool providers. An MCP server exposes tools — the agent discovers them at startup and can invoke them just like custom tools.

```mermaid
graph LR
    A[Your Agent] -->|stdio| B[Local MCP Server]
    A -->|HTTP| C[Remote MCP Server]
    B --> D[File System]
    C --> E[External API]
```

<Callout type="info">
  MCP tools are discovered at runtime when `agent.start()` is called. The agent doesn't need to know about them at build time.
</Callout>

***

## Installation

MCP support requires additional dependencies:

```bash
npm install @ai-sdk/mcp @modelcontextprotocol/sdk
```

***

## MCP Client Builder

### Stdio Transport (Local Process)

Spawns a local process and communicates via stdin/stdout:

```typescript
import { IgniterAgentMCPClient } from '@igniter-js/agents'

const filesystemMCP = IgniterAgentMCPClient
  .create('filesystem')
  .withType('stdio')
  .withCommand('npx')
  .withArgs([
    '-y',
    '@modelcontextprotocol/server-filesystem',
    '/home/user/workspace',
  ])
  .withEnv({
    DEBUG: 'mcp:*',
    HOME: process.env.HOME!,
  })
  .build()
```

### HTTP Transport (Remote Server)

Connects to a remote MCP server over HTTP/HTTPS:

```typescript
const remoteMCP = IgniterAgentMCPClient
  .create('opencode')
  .withType('http')
  .withURL('https://sandbox.example.com/mcp')
  .withHeaders({
    'Authorization': `Bearer ${process.env.MCP_API_KEY}`,
    'Content-Type': 'application/json',
  })
  .build()
```

***

## MCP Client Builder API

### Common Methods

| Method                         | Description                                         |
| ------------------------------ | --------------------------------------------------- |
| `.create(name)`                | Creates a new MCP client builder with a unique name |
| `.withType('stdio' \| 'http')` | Sets the transport type (required)                  |
| `.withName(name)`              | Renames the configuration                           |
| `.build()`                     | Returns the built MCP config                        |

### Stdio-Specific Methods

| Method              | Description                                            |
| ------------------- | ------------------------------------------------------ |
| `.withCommand(cmd)` | The command to execute (e.g., `npx`, `node`, `python`) |
| `.withArgs(args)`   | Command-line arguments array                           |
| `.withEnv(env)`     | Environment variables record                           |

### HTTP-Specific Methods

| Method                  | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `.withURL(url)`         | The MCP server endpoint URL                    |
| `.withHeaders(headers)` | HTTP headers record (auth, content-type, etc.) |

***

## Registering MCP Clients

Use `.addMCP()` on the agent builder:

```typescript
const agent = IgniterAgent
  .create('multi-mcp-agent')
  .withModel(openai('gpt-4o'))
  .addMCP(filesystemMCP)
  .addMCP(githubMCP)
  .addMCP(remoteMCP)
  .build()

// All MCP connections are established here
await agent.start()
```

<Callout type="warn">
  MCP connections are **established at `start()` time, not at build time**. If an MCP server is unreachable, `start()` will throw an error. Use `.onMCPError()` to handle connection failures gracefully.
</Callout>

***

## Real-World MCP Examples

### GitHub MCP Server

```typescript
const githubMCP = IgniterAgentMCPClient
  .create('github')
  .withType('stdio')
  .withCommand('npx')
  .withArgs(['-y', '@modelcontextprotocol/server-github'])
  .withEnv({
    GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN!,
  })
  .build()
```

### Brave Search MCP

```typescript
const searchMCP = IgniterAgentMCPClient
  .create('brave-search')
  .withType('stdio')
  .withCommand('npx')
  .withArgs(['-y', '@modelcontextprotocol/server-brave-search'])
  .withEnv({
    BRAVE_API_KEY: process.env.BRAVE_API_KEY!,
  })
  .build()
```

### PostgreSQL MCP

```typescript
const postgresMCP = IgniterAgentMCPClient
  .create('database')
  .withType('stdio')
  .withCommand('npx')
  .withArgs(['-y', '@modelcontextprotocol/server-postgres'])
  .withEnv({
    DATABASE_URL: process.env.DATABASE_URL!,
  })
  .build()
```

***

## MCP Lifecycle

```
agent.build()       → MCP configs are registered (not connected)
agent.start()       → Each MCP is connected in sequence
                      Tools are discovered from each server
                      Hooks fire: onMCPStart for each connection
agent.generate()    → AI can use tools from all connected MCPs
agent.stop()        → Each MCP is disconnected gracefully
```

### Error Handling

```typescript
const agent = IgniterAgent
  .create('robust-agent')
  .withModel(openai('gpt-4o'))
  .addMCP(filesystemMCP)
  .onMCPStart((agentName, mcp) => {
    console.log(`✅ ${agentName}: MCP '${mcp}' connected`)
  })
  .onMCPError((agentName, mcp, error) => {
    console.error(`❌ ${agentName}: MCP '${mcp}' failed:`, error.message)
  })
  .build()

try {
  await agent.start()
} catch (error) {
  console.error('Agent startup failed:', error)
}
```

***

## MCP vs Custom Tools

| Feature         | Custom Tools                | MCP Tools                 |
| --------------- | --------------------------- | ------------------------- |
| **Definition**  | In-code with Zod schemas    | Discovered at runtime     |
| **Type Safety** | Full compile-time inference | Runtime only              |
| **Deployment**  | Bundled with your app       | External process/server   |
| **Updates**     | Require redeploy            | Independent               |
| **Use Case**    | App-specific logic          | Shared/standardized tools |

<Callout type="info">
  Use **custom tools** for your application's core business logic. Use **MCP** for standardized tools (filesystem, database, search, GitHub) that can be shared across agents and maintained independently.
</Callout>

***

## Next Steps

* [Multi-Agent Orchestration](/docs/agents/multi-agent) — Manage multiple agents with a single manager
* [Hooks & Telemetry](/docs/agents/hooks-telemetry) — Monitor MCP connections with telemetry events


---

# Memory System

> Persistent memory for agent conversations. Working memory, chat history, chat sessions, in-memory adapter, JSON file adapter, and building custom adapters.
URL: https://igniterjs.com/docs/agents/memory

## Memory System

The memory system enables agents to maintain context across multiple conversation turns. It provides three layers of persistence: **working memory** (key-value state), **chat history** (message logs), and **chat sessions** (conversation metadata). All layers are backed by pluggable adapters.

***

## Memory Architecture

```
┌──────────────────────────────────────────────┐
│              IgniterAgentMemoryCore           │
│  (telemetry wrapping, error handling, logging) │
├──────────────────────────────────────────────┤
│              Memory Provider Interface         │
├──────────────┬──────────────┬────────────────┤
│  Working     │   Chat       │   Chat         │
│  Memory      │   History    │   Sessions     │
│  (key-value) │  (messages)  │  (metadata)    │
├──────────────┴──────────────┴────────────────┤
│              Adapter Implementations           │
├──────────────┬──────────────┬────────────────┤
│  In-Memory   │  JSON File   │   Custom       │
│  Adapter     │  Adapter     │   (Redis, PG)  │
└──────────────┴──────────────┴────────────────┘
```

***

## Enabling Memory

Memory is configured on the agent builder via `.withMemory()`:

```typescript
import { IgniterAgentInMemoryAdapter } from '@igniter-js/agents'

const adapter = IgniterAgentInMemoryAdapter.create({
  namespace: 'my-app',
  maxChats: 50,
})

const memoryConfig = {
  provider: adapter,
  working: { enabled: true, scope: 'chat' },
  history: { enabled: true, limit: 100 },
  chats: { enabled: true },
}

const agent = IgniterAgent
  .create('memory-bot')
  .withModel(openai('gpt-4o'))
  .withMemory(memoryConfig)
  .build()
```

### Memory Config Options

| Option            | Type                         | Description                                                |
| ----------------- | ---------------------------- | ---------------------------------------------------------- |
| `provider`        | `IgniterAgentMemoryProvider` | The adapter instance                                       |
| `working.enabled` | `boolean`                    | Enable working memory (key-value state)                    |
| `working.scope`   | `string`                     | Scope key for working memory (e.g., `'chat'`, `'session'`) |
| `history.enabled` | `boolean`                    | Enable chat message history                                |
| `history.limit`   | `number`                     | Maximum messages to keep per chat                          |
| `chats.enabled`   | `boolean`                    | Enable chat session management                             |

***

## Working Memory

Working memory provides a key-value store scoped to an identifier (typically the chat ID). It's ideal for storing preferences, state, and transient context.

```typescript
// Inside the agent's memory runtime:
await agent.memory.updateWorkingMemory({
  scope: 'chat',
  identifier: 'chat_123',
  content: 'User prefers TypeScript. Uses VS Code. Project: igniter-js.',
})

const memory = await agent.memory.getWorkingMemory({
  scope: 'chat',
  identifier: 'chat_123',
})

console.log(memory?.content)
// → "User prefers TypeScript. Uses VS Code. Project: igniter-js."
console.log(memory?.updatedAt)
// → 2026-06-02T17:00:00.000Z
```

<Callout type="info">
  Working memory is automatically injected into the agent's context before each generation call, so the AI can reference it in its responses.
</Callout>

***

## Chat History & Sessions

The memory system manages full conversation persistence:

```typescript
// Messages are automatically saved during generation
// You can also query them:
const messages = await agent.memory.getMessages({
  chatId: 'chat_123',
  limit: 50,
})

// Manage chat sessions
await agent.memory.saveChat({
  chatId: 'chat_123',
  userId: 'user_001',
  title: 'TypeScript Help',
  createdAt: new Date(),
  updatedAt: new Date(),
  messageCount: 12,
})

const chats = await agent.memory.getChats({
  userId: 'user_001',
})

await agent.memory.updateChatTitle('chat_123', 'Updated Title')
await agent.memory.deleteChat('chat_123')
```

***

## Built-in Adapters

### In-Memory Adapter

For development, testing, and short-lived applications. Data is lost on restart.

```typescript
import { IgniterAgentInMemoryAdapter } from '@igniter-js/agents'

const adapter = IgniterAgentInMemoryAdapter.create({
  namespace: 'dev',       // Namespace for multi-app isolation
  maxMessages: 1000,      // Max messages per chat (default: 1000)
  maxChats: 100,          // Max chat sessions (default: 100)
})

// Utility methods
await adapter.clear()                  // Clear all data
console.log(adapter.isConnected())    // Always true
```

### JSON File Adapter

For single-machine production deployments. Data persists to a JSON file.

```typescript
import { IgniterAgentJSONFileAdapter } from '@igniter-js/agents'

const adapter = IgniterAgentJSONFileAdapter.create({
  filePath: './data/agent-memory.json',
  namespace: 'prod',
})

// Data is automatically persisted to disk
// Survives process restarts
```

<Callout type="warn">
  JSON File adapter is suitable for single-machine deployments. For multi-server architectures, use a shared backend like Redis or PostgreSQL via a custom adapter.
</Callout>

***

## Building a Custom Adapter

Implement the `IgniterAgentMemoryProvider` interface to create a custom adapter:

```typescript
import type {
  IgniterAgentMemoryProvider,
  IgniterAgentWorkingMemory,
  IgniterAgentConversationMessage,
  IgniterAgentChatSession,
  IgniterAgentWorkingMemoryParams,
  IgniterAgentUpdateWorkingMemoryParams,
  IgniterAgentGetMessagesParams,
  IgniterAgentGetChatsParams,
} from '@igniter-js/agents'

class RedisMemoryAdapter implements IgniterAgentMemoryProvider {
  constructor(private redis: Redis) {}

  // Working memory
  async getWorkingMemory(params: IgniterAgentWorkingMemoryParams) {
    const key = `wm:${params.scope}:${params.identifier}`
    return this.redis.get(key).then(JSON.parse)
  }

  async updateWorkingMemory(params: IgniterAgentUpdateWorkingMemoryParams) {
    const key = `wm:${params.scope}:${params.identifier}`
    await this.redis.set(key, JSON.stringify({
      content: params.content,
      updatedAt: new Date().toISOString(),
    }))
  }

  // Messages
  async saveMessage(message: IgniterAgentConversationMessage) {
    const key = `msgs:${message.chatId}`
    await this.redis.lpush(key, JSON.stringify(message))
    await this.redis.ltrim(key, 0, 999) // Keep last 1000
  }

  async getMessages<T>(params: IgniterAgentGetMessagesParams) {
    const key = `msgs:${params.chatId}`
    const raw = await this.redis.lrange(key, 0, params.limit ?? 50)
    return raw.map(m => JSON.parse(m)) as T[]
  }

  // Chat sessions
  async saveChat(chat: IgniterAgentChatSession) {
    await this.redis.hset('chats', chat.chatId, JSON.stringify(chat))
  }

  async getChats(params: IgniterAgentGetChatsParams) {
    const raw = await this.redis.hvals('chats')
    return raw.map(c => JSON.parse(c))
  }

  async getChat(chatId: string) {
    const raw = await this.redis.hget('chats', chatId)
    return raw ? JSON.parse(raw) : null
  }

  async updateChatTitle(chatId: string, title: string) {
    const chat = await this.getChat(chatId)
    if (chat) {
      chat.title = title
      await this.saveChat(chat)
    }
  }

  async deleteChat(chatId: string) {
    await this.redis.hdel('chats', chatId)
    await this.redis.del(`msgs:${chatId}`)
  }
}
```

### Memory Provider Interface

| Method                           | Required | Description                         |
| -------------------------------- | -------- | ----------------------------------- |
| `getWorkingMemory(params)`       | No       | Retrieve scoped working memory      |
| `updateWorkingMemory(params)`    | No       | Update/create scoped working memory |
| `saveMessage(message)`           | No       | Save a conversation message         |
| `getMessages(params)`            | No       | Get messages for a chat             |
| `saveChat(chat)`                 | No       | Save/update a chat session          |
| `getChats(params)`               | No       | List chat sessions                  |
| `getChat(chatId)`                | No       | Get a single chat session           |
| `updateChatTitle(chatId, title)` | No       | Update chat title                   |
| `deleteChat(chatId)`             | No       | Delete a chat and its messages      |

***

## Telemetry & Memory

When telemetry is enabled, every memory operation emits structured events:

| Event                                    | Attributes                                                   |
| ---------------------------------------- | ------------------------------------------------------------ |
| `igniter.agent.memory.operation.started` | `ctx.agent.name`, `ctx.memory.operation`, `ctx.memory.scope` |
| `igniter.agent.memory.operation.success` | + `ctx.memory.durationMs`, `ctx.memory.count`                |
| `igniter.agent.memory.operation.error`   | + `ctx.error.code`, `ctx.error.message`                      |


---

# Multi-Agent Orchestration

> Manage multiple specialized agents with a single manager. Agent registration, batch start/stop, shared telemetry, lifecycle hooks, and routing.
URL: https://igniterjs.com/docs/agents/multi-agent

## Multi-Agent Orchestration

`IgniterAgentManager` provides centralized orchestration for multiple agents. It shares common resources (logger, telemetry, hooks), manages lifecycle in batch, and enables request routing between agents.

***

## The Manager Builder

Like the agent builder, the manager uses a fluent API:

```typescript
import {
  IgniterAgentManager,
  IgniterAgent,
} from '@igniter-js/agents'
import { openai } from '@ai-sdk/openai'

// Create specialized agents
const supportAgent = IgniterAgent
  .create('support')
  .withModel(openai('gpt-4o'))
  .withPrompt(IgniterAgentPrompt.create('You are customer support.'))
  .build()

const salesAgent = IgniterAgent
  .create('sales')
  .withModel(openai('gpt-4o'))
  .withPrompt(IgniterAgentPrompt.create('You are a sales representative.'))
  .build()

const codeAgent = IgniterAgent
  .create('code')
  .withModel(openai('gpt-4o'))
  .addToolset(codeToolset)
  .build()

// Create the manager
const manager = IgniterAgentManager
  .create()
  .addAgent('support', supportAgent)
  .addAgent('sales', salesAgent)
  .addAgent('code', codeAgent)
  .withAutoStart(true)          // Start agents immediately
  .withContinueOnError(true)    // Don't fail all if one errors
  .build()
```

***

## Manager Builder API

| Method                       | Description                                                     |
| ---------------------------- | --------------------------------------------------------------- |
| `.create()`                  | Creates a new manager builder                                   |
| `.addAgent(name, agent)`     | Registers an agent (type-safe — names are tracked in the type)  |
| `.withLogger(logger)`        | Shared logger for all agents                                    |
| `.withTelemetry(telemetry)`  | Shared telemetry for all agents                                 |
| `.withAutoStart(bool)`       | Auto-start agents on registration (default: `false`)            |
| `.withContinueOnError(bool)` | Continue if an agent fails during batch start (default: `true`) |
| `.onAgentStart(callback)`    | Fired when any agent starts                                     |
| `.onAgentError(callback)`    | Fired when any agent errors                                     |
| `.onToolCallStart(callback)` | Fired when any tool call starts                                 |
| `.onToolCallEnd(callback)`   | Fired when any tool call completes                              |
| `.onToolCallError(callback)` | Fired when any tool call fails                                  |
| `.onMCPStart(callback)`      | Fired when any MCP connection starts                            |
| `.onMCPError(callback)`      | Fired when any MCP connection fails                             |
| `.build()`                   | Returns the built manager                                       |

***

## Agent Registration & Lifecycle

### Programmatic Registration

Agents can also be registered after the manager is built:

```typescript
const manager = IgniterAgentManager.create().build()

manager.register('support', supportAgent)
manager.register('sales', salesAgent)

// Check registration
console.log(manager.has('support'))   // true
console.log(manager.has('unknown'))   // false

// Unregister an agent
manager.unregister('old-agent')
```

<Callout type="warn">
  Registering an agent with a name that already exists throws `IgniterAgentError` with code `INVALID_CONFIG`.
</Callout>

### Starting and Managing Agents

```typescript
// Start a single agent
await manager.start('support')

// Start all agents in parallel
const results = await manager.startAll()

for (const [name, result] of results) {
  if (result instanceof Error) {
    console.error(`❌ ${name} failed:`, result.message)
  } else {
    console.log(`✅ ${name} started with ${Object.keys(result).length} toolsets`)
  }
}

// Get agent names
console.log(manager.getNames())       // ['support', 'sales', 'code']

// Get agent status
console.log(manager.getStatus())
// → [{ name: 'support', status: 'running', ... }, ...]

// Get failed agents
console.log(manager.getFailedAgents())
// → [{ name: 'code', error: Error(...), ... }]
```

***

## Using Agents via the Manager

### Direct Access

```typescript
// Get an agent by name
const support = manager.get('support')

const result = await support.generate({
  chatId: 'chat_001',
  userId: 'user_001',
  context: {},
  message: { role: 'user', content: 'I need help with my order' },
})

console.log(result.content)
```

### Agent Routing Pattern

Build a router that selects the right agent based on the request:

```typescript
type AgentName = 'support' | 'sales' | 'code'

function routeRequest(intent: string): AgentName {
  switch (intent) {
    case 'help':
    case 'refund':
      return 'support'
    case 'pricing':
    case 'demo':
      return 'sales'
    case 'debug':
    case 'code':
      return 'code'
    default:
      return 'support'
  }
}

async function handleRequest(intent: string, message: string) {
  const agentName = routeRequest(intent)
  const agent = manager.get(agentName)

  return agent.generate({
    chatId: `chat_${Date.now()}`,
    userId: 'user_001',
    context: { intent },
    message: { role: 'user', content: message },
  })
}
```

***

## Shared Hooks & Observability

Manager-level hooks apply to all registered agents:

```typescript
const manager = IgniterAgentManager
  .create()
  .addAgent('support', supportAgent)
  .addAgent('sales', salesAgent)
  .onAgentStart((name) => {
    console.log(`🚀 Agent '${name}' started`)
  })
  .onAgentError((name, error) => {
    console.error(`💥 Agent '${name}' failed:`, error.message)
  })
  .onToolCallStart((agentName, toolName, input) => {
    console.log(`🔧 [${agentName}] → ${toolName}`)
  })
  .onToolCallEnd((agentName, toolName, output) => {
    console.log(`✅ [${agentName}] ← ${toolName}`)
  })
  .build()
```

### Shared Telemetry

When telemetry is configured on the manager, it's automatically propagated to all agents:

```typescript
import { IgniterTelemetry } from '@igniter-js/telemetry'

const telemetry = IgniterTelemetry.create().build()

const manager = IgniterAgentManager
  .create()
  .withTelemetry(telemetry)
  .withLogger(myLogger)
  .addAgent('support', supportAgent)
  .addAgent('sales', salesAgent)
  .build()

// All agents now share the same telemetry and logger
```

***

## Agent Status Lifecycle

Each agent tracked by the manager goes through these states:

| Status     | Description                                 |
| ---------- | ------------------------------------------- |
| `idle`     | Registered but not yet started              |
| `starting` | Currently initializing MCP connections      |
| `running`  | Successfully started and ready for requests |
| `error`    | Failed to start or encountered an error     |

```typescript
const status = manager.getStatus()
status.forEach(s => {
  console.log(`${s.name}: ${s.status}`)
  console.log(`  Registered: ${s.registeredAt}`)
  console.log(`  Started: ${s.startedAt ?? 'N/A'}`)
  console.log(`  Toolsets: ${s.toolsetCount}`)
  if (s.error) {
    console.log(`  Error: ${s.error.message}`)
  }
})
```

***

## Complete Multi-Agent System

```typescript
import {
  IgniterAgent,
  IgniterAgentManager,
  IgniterAgentTool,
  IgniterAgentToolset,
  IgniterAgentPrompt,
} from '@igniter-js/agents'
import { openai } from '@ai-sdk/openai'
import { z } from 'zod'

// Support agent with a knowledge base tool
const searchKB = IgniterAgentTool
  .create('search_kb')
  .withDescription('Search the support knowledge base')
  .withInput(z.object({ query: z.string() }))
  .withExecute(async ({ query }) => {
    return kb.search(query)
  })
  .build()

const supportAgent = IgniterAgent
  .create('support')
  .withModel(openai('gpt-4o'))
  .withPrompt(IgniterAgentPrompt.create('You are Tier 1 support.'))
  .addToolset(
    IgniterAgentToolset.create('kb').addTool(searchKB).build()
  )
  .build()

// Code agent with an execution tool
const runCode = IgniterAgentTool
  .create('run')
  .withDescription('Execute code in a sandbox')
  .withInput(z.object({ code: z.string(), language: z.string() }))
  .withExecute(async ({ code, language }) => {
    return sandbox.execute(code, language)
  })
  .build()

const codeAgent = IgniterAgent
  .create('code')
  .withModel(openai('gpt-4o'))
  .withPrompt(IgniterAgentPrompt.create('You are a senior developer.'))
  .addToolset(
    IgniterAgentToolset.create('sandbox').addTool(runCode).build()
  )
  .build()

// Manager orchestrates both
const manager = IgniterAgentManager
  .create()
  .addAgent('support', supportAgent)
  .addAgent('code', codeAgent)
  .withContinueOnError(true)
  .onAgentStart((name) => console.log(`✅ ${name} is live`))
  .onAgentError((name, err) => console.error(`❌ ${name}:`, err.message))
  .build()

// Start all agents
const results = await manager.startAll()
console.log('Running agents:', manager.getNames())
```


---

# Prompts

> Create dynamic system prompts with {{variable}} interpolation, appended prompts for modular instruction composition, and context-aware templates.
URL: https://igniterjs.com/docs/agents/prompts

## Prompts

`IgniterAgentPrompt` provides a lightweight template system for building agent system instructions with `{{variable}}` interpolation and support for composing prompts from multiple sources.

***

## Basic Templates

Use `{{variable}}` syntax to inject context data into your prompts:

```typescript
import { IgniterAgentPrompt, IgniterAgent } from '@igniter-js/agents'

const prompt = IgniterAgentPrompt
  .create('You are {{role}}. Your tone is {{tone}}. User: {{user.name}}')

const agent = IgniterAgent
  .create('bot')
  .withModel(openai('gpt-4o'))
  .withPrompt(prompt)
  .build()

const result = await agent.generate({
  chatId: 'chat_001',
  userId: 'user_001',
  context: {
    role: 'customer support',
    tone: 'friendly and professional',
    user: { name: 'Alice' },
  },
  message: { role: 'user', content: 'Hello!' },
})

// System prompt resolves to:
// "You are customer support. Your tone is friendly and professional. User: Alice"
```

### How Interpolation Works

* Variables are resolved by dot-path from the `context` object
* `{{role}}` → `context.role`
* `{{user.name}}` → `context.user.name`
* `{{company.address.city}}` → `context.company.address.city`
* Missing variables resolve to an empty string `""`
* `null` values resolve to an empty string

<Callout type="warn">
  Variable names are case-sensitive and must match the context keys exactly. `{{role}}` and `{{Role}}` are different variables.
</Callout>

***

## Dynamic Prompt Examples

### Multi-Language Support

```typescript
const multilingualPrompt = IgniterAgentPrompt.create(`
  You are a {{role}}.
  Always respond in {{language}}.
  {{#preferences.formal}}
  Use formal language.
  {{/preferences.formal}}
`)

const result = await agent.generate({
  chatId: 'chat_001',
  userId: 'user_001',
  context: {
    role: 'travel agent',
    language: 'Portuguese',
  },
  message: { role: 'user', content: 'Find me a flight' },
})
```

### Role-Based Prompts

```typescript
const roleAwarePrompt = IgniterAgentPrompt.create(`
  You are {{agent.name}}, a {{agent.role}}.
  
  Capabilities:
  {{agent.capabilities}}
  
  Current user: {{user.email}}
  Role: {{user.role}}
`)

// Different contexts produce different prompts
await agent.generate({
  chatId: 'chat_001',
  userId: 'user_admin',
  context: {
    agent: {
      name: 'Atlas',
      role: 'system administrator',
      capabilities: '- Manage users\n- Configure database\n- Monitor logs',
    },
    user: { email: 'admin@corp.com', role: 'admin' },
  },
  message: { role: 'user', content: 'Check system status' },
})
```

***

## Appended Prompts

Compose prompts from multiple sources using `.addAppended()`:

```typescript
import { IgniterAgentPrompt } from '@igniter-js/agents'

// Base prompt
const basePrompt = IgniterAgentPrompt.create(`
  You are {{agent.role}}.
`)

// Add capability-specific prompts
const prompt = basePrompt
  .addAppended('tools', `
    Available tools: {{agent.tools}}
  `)
  .addAppended('rules', `
    Rules:
    - Never share sensitive data
    - Always ask for confirmation before destructive actions
  `)
  .addAppended('context', `
    Current date: {{system.date}}
    Environment: {{system.env}}
  `)

// Full prompt when built:
// You are developer assistant.
//
// Available tools: github, docker, database
//
// Rules:
// - Never share sensitive data
// - Always ask for confirmation before destructive actions
//
// Current date: 2026-06-02
// Environment: production
```

### Managing Appended Prompts

```typescript
// Remove an appended prompt
const withoutContext = prompt.removeAppended('context')

// Check what's appended
console.log(prompt.getAppended()) // { tools: ..., rules: ..., context: ... }

// Get the base template
console.log(prompt.getTemplate()) // "You are {{agent.role}}."
```

<Callout type="info">
  Appended prompts are joined with `\n\n` and interpolated with the same context. Each appended prompt can be a string or another `IgniterAgentPrompt` instance.
</Callout>

***

## Pattern: Composable Prompt Library

Build a library of reusable prompt snippets:

```typescript
// lib/prompts/base.ts
export const basePrompt = (role: string) =>
  IgniterAgentPrompt.create(`You are ${role}.`)

// lib/prompts/security.ts
export const securityRules = IgniterAgentPrompt.create(`
  Security Rules:
  - Never expose API keys or secrets
  - Validate all user input
  - Log all data access
`)

// lib/prompts/tool-usage.ts
export const toolUsageGuide = IgniterAgentPrompt.create(`
  Tool Usage:
  - Call tools when you need external data
  - Handle tool errors gracefully
  - Cite tool sources in responses
`)
```

```typescript
// Compose for a specific agent
import { basePrompt, securityRules, toolUsageGuide } from './lib/prompts'

const prompt = basePrompt('security analyst')
  .addAppended('security', securityRules)
  .addAppended('tools', toolUsageGuide)

const agent = IgniterAgent
  .create('security-bot')
  .withModel(openai('gpt-4o'))
  .withPrompt(prompt)
  .build()
```

***

## API Reference

### `IgniterAgentPromptBuilder`

| Method                      | Description                                           |
| --------------------------- | ----------------------------------------------------- |
| `.create(template)`         | Creates a new prompt builder with a template string   |
| `.build(context)`           | Renders the template with the provided context data   |
| `.addAppended(key, prompt)` | Appends another prompt (string or IgniterAgentPrompt) |
| `.removeAppended(key)`      | Removes an appended prompt by key                     |
| `.getAppended()`            | Returns the appended prompts object                   |
| `.getTemplate()`            | Returns the raw template string                       |


---

# Quick Start

> Build your first Igniter.js agent in under 5 minutes. Three complete scenarios basic agent with tools, agent with persistent memory, and agent with MCP integration.
URL: https://igniterjs.com/docs/agents/quick-start

## Quick Start

Choose your scenario below. Each takes under 5 minutes from zero to a working agent.

<Callout type="info">
  Make sure you've completed the [installation](/docs/agents/installation) step first.
</Callout>

***

## Scenario 1: Basic Agent with a Custom Tool

The most common pattern — define a tool, group it in a toolset, and wire it into an agent.

<Steps>
  <Step>
    ### Import Dependencies

    ```typescript
    import {
      IgniterAgent,
      IgniterAgentTool,
      IgniterAgentToolset,
    } from '@igniter-js/agents'
    import { openai } from '@ai-sdk/openai'
    import { z } from 'zod'
    ```
  </Step>

  <Step>
    ### Define a Tool

    Every tool needs a **name**, **description** (the AI uses this to decide when to call it), **input schema** (Zod), and an **execute handler**.

    ```typescript
    const weatherTool = IgniterAgentTool
      .create('get_weather')
      .withDescription('Get current weather for a location')
      .withInput(
        z.object({
          location: z.string().describe('City name or coordinates'),
          unit: z.enum(['C', 'F']).default('C'),
        })
      )
      .withExecute(async ({ location, unit }) => {
        // Replace with your real weather API call
        const response = await fetch(
          `https://api.weather.example/current?q=${location}&units=${unit}`
        )
        return response.json()
      })
      .build()
    ```
  </Step>

  <Step>
    ### Create a Toolset

    Toolsets group related tools by domain. The toolset name becomes a prefix for each tool when the AI sees them.

    ```typescript
    const weatherToolset = IgniterAgentToolset
      .create('weather')
      .addTool(weatherTool)
      .build()
    ```
  </Step>

  <Step>
    ### Build and Run the Agent

    ```typescript
    const agent = IgniterAgent
      .create('weather-assistant')
      .withModel(openai('gpt-4o-mini'))
      .addToolset(weatherToolset)
      .build()

    // Start initializes MCP connections (none here, but always call it)
    await agent.start()

    // Generate a response — the AI decides whether to use the tool
    const result = await agent.generate({
      chatId: 'chat_001',
      userId: 'user_001',
      context: {},
      message: {
        role: 'user',
        content: "What's the weather like in Tokyo?",
      },
    })

    console.log(result.content)
    ```
  </Step>
</Steps>

**✅ Success!** You've built an agent that can decide when to call your tool and use the result in its response.

***

## Scenario 2: Agent with Persistent Memory

For multi-turn conversations where the agent needs to remember past interactions.

<Steps>
  <Step>
    ### Create a Memory Adapter

    ```typescript
    import {
      IgniterAgent,
      IgniterAgentInMemoryAdapter,
      IgniterAgentPrompt,
    } from '@igniter-js/agents'
    import { openai } from '@ai-sdk/openai'

    const memoryAdapter = IgniterAgentInMemoryAdapter.create({
      namespace: 'my-app',
      maxChats: 50,
    })
    ```

    <Callout type="info">
      `IgniterAgentInMemoryAdapter` is great for development. For production, use `IgniterAgentJSONFileAdapter` or build a custom adapter (Redis, PostgreSQL, etc.).
    </Callout>
  </Step>

  <Step>
    ### Configure Memory and Build Agent

    ```typescript
    const memoryConfig = {
      provider: memoryAdapter,
      working: { enabled: true, scope: 'chat' },
      history: { enabled: true, limit: 100 },
      chats: { enabled: true },
    }

    const agent = IgniterAgent
      .create('memory-bot')
      .withModel(openai('gpt-4o-mini'))
      .withMemory(memoryConfig)
      .withPrompt(
        IgniterAgentPrompt.create(
          'You are a helpful assistant. Remember details about the user across messages.'
        )
      )
      .build()

    await agent.start()
    ```
  </Step>

  <Step>
    ### Run a Multi-Turn Conversation

    ```typescript
    // First turn
    let response = await agent.generate({
      chatId: 'chat_memory_001',
      userId: 'user_001',
      context: {},
      message: {
        role: 'user',
        content: 'My name is Alice and my favorite color is blue.',
      },
    })
    console.log('Turn 1:', response.content)

    // Second turn — agent remembers from the first
    response = await agent.generate({
      chatId: 'chat_memory_001',
      userId: 'user_001',
      context: {},
      message: {
        role: 'user',
        content: "What's my name and favorite color?",
      },
    })
    console.log('Turn 2:', response.content)
    // → "Your name is Alice and your favorite color is blue."
    ```
  </Step>
</Steps>

**✅ Success!** The agent maintains context across turns using the memory adapter.

***

## Scenario 3: Agent with MCP Integration

Connect to external tools via the Model Context Protocol.

<Steps>
  <Step>
    ### Install MCP Dependencies

    ```bash
    npm install @ai-sdk/mcp @modelcontextprotocol/sdk
    ```
  </Step>

  <Step>
    ### Configure an MCP Client

    ```typescript
    import {
      IgniterAgent,
      IgniterAgentMCPClient,
    } from '@igniter-js/agents'
    import { openai } from '@ai-sdk/openai'

    // Stdio transport — spawns a local process
    const filesystemMCP = IgniterAgentMCPClient
      .create('filesystem')
      .withType('stdio')
      .withCommand('npx')
      .withArgs([
        '-y',
        '@modelcontextprotocol/server-filesystem',
        '/tmp/agent-workspace',
      ])
      .withEnv({ DEBUG: 'mcp:*' })
      .build()

    // HTTP transport — connects to a remote server
    const remoteMCP = IgniterAgentMCPClient
      .create('opencode')
      .withType('http')
      .withURL('https://sandbox.example.com/mcp')
      .withHeaders({
        'X-API-Key': process.env.MCP_API_KEY!,
      })
      .build()
    ```
  </Step>

  <Step>
    ### Build and Use the Agent

    ```typescript
    const agent = IgniterAgent
      .create('mcp-agent')
      .withModel(openai('gpt-4o-mini'))
      .addMCP(filesystemMCP)
      .addMCP(remoteMCP)
      .build()

    // MCP connections are established here
    await agent.start()

    const result = await agent.generate({
      chatId: 'chat_mcp_001',
      userId: 'user_001',
      context: {},
      message: {
        role: 'user',
        content: 'List all files in my workspace directory.',
      },
    })

    console.log(result.content)
    ```
  </Step>
</Steps>

**✅ Success!** Your agent can now use tools from remote MCP servers, discovered at runtime.

***

## Next Steps

* [Building Agents](/docs/agents/building-agents) — Full agent builder API reference
* [Tools & Toolsets](/docs/agents/tools-toolsets) — Creating type-safe tools in depth
* [Memory System](/docs/agents/memory) — Working memory, chat history, and custom adapters
* [MCP Integration](/docs/agents/mcp-integration) — Stdio, HTTP transports, and server discovery


---

# Real-World Examples

> Production-ready agent patterns. Customer support triage, code review assistant, data analyst with database tools, e-commerce concierge, and multi-agent workflow orchestrator.
URL: https://igniterjs.com/docs/agents/real-world

## Real-World Examples

Five complete, production-ready agent patterns that demonstrate the full capabilities of `@igniter-js/agents`.

***

## 1. Customer Support Triage Agent

An agent that classifies support tickets, searches the knowledge base, and escalates when needed.

```typescript
import {
  IgniterAgent,
  IgniterAgentTool,
  IgniterAgentToolset,
  IgniterAgentPrompt,
  IgniterAgentInMemoryAdapter,
} from '@igniter-js/agents'
import { openai } from '@ai-sdk/openai'
import { z } from 'zod'

// Tool: Search knowledge base
const searchKB = IgniterAgentTool
  .create('search_kb')
  .withDescription('Search the support knowledge base for relevant articles')
  .withInput(
    z.object({
      query: z.string().describe('Search query'),
      category: z.enum(['billing', 'technical', 'account']).optional(),
    })
  )
  .withExecute(async ({ query, category }) => {
    const articles = await knowledgeBase.search(query, { category })
    return articles.map(a => ({
      id: a.id,
      title: a.title,
      relevance: a.score,
      summary: a.summary,
    }))
  })
  .build()

// Tool: Create escalation ticket
const createEscalation = IgniterAgentTool
  .create('escalate')
  .withDescription('Create an escalation ticket when the issue cannot be resolved')
  .withInput(
    z.object({
      priority: z.enum(['high', 'critical']),
      summary: z.string(),
      category: z.string(),
      evidence: z.string().optional(),
    })
  )
  .withExecute(async ({ priority, summary, category, evidence }) => {
    const ticket = await ticketing.create({
      priority,
      summary,
      category,
      evidence,
      source: 'ai-triage',
    })
    return { ticketId: ticket.id, status: 'escalated' }
  })
  .build()

// Tool: Check order status
const checkOrder = IgniterAgentTool
  .create('check_order')
  .withDescription('Look up an order by ID and return its status')
  .withInput(z.object({ orderId: z.string() }))
  .withExecute(async ({ orderId }) => {
    const order = await orders.findById(orderId)
    if (!order) return { found: false }
    return {
      found: true,
      status: order.status,
      items: order.items.length,
      estimatedDelivery: order.estimatedDelivery,
    }
  })
  .build()

// Build the support toolset
const supportToolset = IgniterAgentToolset
  .create('support')
  .addTool(searchKB)
  .addTool(createEscalation)
  .addTool(checkOrder)
  .build()

// Memory for tracking support history
const memory = IgniterAgentInMemoryAdapter.create({
  namespace: 'support',
  maxChats: 1000,
})

// The triage agent
const triageAgent = IgniterAgent
  .create('support-triage')
  .withModel(openai('gpt-4o'))
  .withPrompt(
    IgniterAgentPrompt.create(`
      You are a Tier 1 support triage agent for {{company}}.
      
      Your process:
      1. Greet the customer warmly
      2. Understand their issue
      3. Search the knowledge base for solutions
      4. If unresolved, escalate with clear evidence
      5. For order issues, always check the order first
      
      Tone: {{tone}}
    `)
  )
  .addToolset(supportToolset)
  .withMemory({
    provider: memory,
    working: { enabled: true, scope: 'ticket' },
    history: { enabled: true, limit: 200 },
    chats: { enabled: true },
  })
  .onToolCallStart((agent, tool) => {
    console.log(`[Support] Starting: ${tool}`)
  })
  .build()

await triageAgent.start()

// Handle a customer request
const result = await triageAgent.generate({
  chatId: 'ticket_0042',
  userId: 'cust_789',
  context: {
    company: 'ShopFast',
    tone: 'empathetic and solution-oriented',
  },
  message: {
    role: 'user',
    content: "Hi, I haven't received my order #ORD-5591. It was supposed to arrive yesterday.",
  },
})
```

***

## 2. Code Review Assistant

An agent with source code analysis tools for automated code review.

```typescript
// Tool: Run linter
const runLinter = IgniterAgentTool
  .create('lint')
  .withDescription('Run ESLint on the provided code and return issues')
  .withInput(
    z.object({
      code: z.string().describe('Source code to lint'),
      filepath: z.string().describe('Virtual filepath for rule matching'),
    })
  )
  .withExecute(async ({ code, filepath }) => {
    const results = await eslint.lintText(code, { filePath: filepath })
    return results.map(r => ({
      file: filepath,
      line: r.line,
      column: r.column,
      rule: r.ruleId,
      message: r.message,
      severity: r.severity === 2 ? 'error' : 'warning',
      fix: r.fix ? 'available' : null,
    }))
  })
  .build()

// Tool: Run type check
const typeCheck = IgniterAgentTool
  .create('typecheck')
  .withDescription('Run TypeScript type checking on code')
  .withInput(
    z.object({
      code: z.string(),
      filename: z.string().default('temp.ts'),
    })
  )
  .withExecute(async ({ code, filename }) => {
    const diagnostics = await ts.createProgram([filename], {
      noEmit: true,
      strict: true,
    })
    return diagnostics.map(d => ({
      line: d.line,
      message: d.messageText,
      code: d.code,
    }))
  })
  .build()

// Tool: Suggest improvements
const suggestRefactor = IgniterAgentTool
  .create('suggest')
  .withDescription('Suggest improvements based on code patterns')
  .withInput(z.object({ code: z.string(), context: z.string().optional() }))
  .withExecute(async ({ code, context }) => {
    // Pattern matching for common anti-patterns
    const patterns = [
      { regex: /\.then\(.*\.catch\(/g, suggestion: 'Use async/await instead of .then chains' },
      { regex: /var\s+/g, suggestion: 'Use const or let instead of var' },
      { regex: /console\.log/g, suggestion: 'Consider using a proper logger' },
    ]
    return patterns
      .filter(p => p.regex.test(code))
      .map(p => ({ pattern: p.regex.source, suggestion: p.suggestion }))
  })
  .build()

const reviewToolset = IgniterAgentToolset
  .create('review')
  .addTool(runLinter)
  .addTool(typeCheck)
  .addTool(suggestRefactor)
  .build()

const codeReviewer = IgniterAgent
  .create('code-reviewer')
  .withModel(openai('gpt-4o'))
  .withPrompt(
    IgniterAgentPrompt.create(`
      You are a senior TypeScript code reviewer.
      
      For each review:
      1. Run the linter to check for style issues
      2. Run the type checker for type safety
      3. Identify improvement patterns
      4. Provide actionable, specific feedback
      
      Always reference exact line numbers and suggest concrete fixes.
    `)
  )
  .addToolset(reviewToolset)
  .build()

await codeReviewer.start()
```

***

## 3. Data Analyst Agent

An agent that can query databases and generate reports.

```typescript
// Tool: Execute SQL query
const queryDB = IgniterAgentTool
  .create('query')
  .withDescription('Execute a read-only SQL query on the analytics database')
  .withInput(
    z.object({
      sql: z.string().describe('SELECT query'),
      params: z.array(z.unknown()).optional(),
      maxRows: z.number().default(100).describe('Maximum rows to return'),
    })
  )
  .withExecute(async ({ sql, params, maxRows }) => {
    const result = await analyticsDB.query({
      text: sql,
      values: params,
      rowMode: 'array',
      maxRows,
    })
    return {
      columns: result.fields.map(f => f.name),
      rows: result.rows,
      rowCount: result.rowCount,
    }
  })
  .build()

// Tool: Generate chart config
const generateChart = IgniterAgentTool
  .create('chart')
  .withDescription('Generate a chart configuration for data visualization')
  .withInput(
    z.object({
      chartType: z.enum(['bar', 'line', 'pie', 'scatter']),
      title: z.string(),
      xAxis: z.string(),
      yAxis: z.string(),
      data: z.array(z.record(z.unknown())),
    })
  )
  .withExecute(async (config) => {
    return { chartConfig: config, renderable: true }
  })
  .build()

const analyticsToolset = IgniterAgentToolset
  .create('analytics')
  .addTool(queryDB)
  .addTool(generateChart)
  .build()

const dataAnalyst = IgniterAgent
  .create('data-analyst')
  .withModel(openai('gpt-4o'))
  .withPrompt(
    IgniterAgentPrompt.create(`
      You are a data analyst. When given a question:
      1. Formulate a SQL query to answer it
      2. Execute the query
      3. Interpret the results in plain language
      4. Suggest a chart if the data warrants it
    `)
  )
  .addToolset(analyticsToolset)
  .build()

await dataAnalyst.start()

const report = await dataAnalyst.generate({
  chatId: 'report_012',
  userId: 'analyst_001',
  context: {},
  message: {
    role: 'user',
    content: 'Show me monthly revenue by product category for Q1 2026.',
  },
})
```

***

## 4. E-Commerce Concierge

A shopping assistant with product search, cart management, and recommendations.

```typescript
const searchProducts = IgniterAgentTool
  .create('search_products')
  .withDescription('Search the product catalog')
  .withInput(
    z.object({
      query: z.string(),
      category: z.string().optional(),
      maxPrice: z.number().optional(),
      inStock: z.boolean().default(true),
      limit: z.number().default(5),
    })
  )
  .withExecute(async (filters) => {
    return catalog.search(filters)
  })
  .build()

const addToCart = IgniterAgentTool
  .create('add_to_cart')
  .withDescription('Add a product to the shopping cart')
  .withInput(
    z.object({
      productId: z.string(),
      quantity: z.number().min(1).max(10).default(1),
    })
  )
  .withExecute(async ({ productId, quantity }) => {
    return cart.add(currentUserId, productId, quantity)
  })
  .build()

const getRecommendations = IgniterAgentTool
  .create('recommend')
  .withDescription('Get personalized product recommendations')
  .withInput(z.object({ basedOn: z.string().optional() }))
  .withExecute(async ({ basedOn }) => {
    return recommendations.forUser(currentUserId, { context: basedOn })
  })
  .build()

const shopToolset = IgniterAgentToolset
  .create('shop')
  .addTool(searchProducts)
  .addTool(addToCart)
  .addTool(getRecommendations)
  .build()

const concierge = IgniterAgent
  .create('shopping-concierge')
  .withModel(openai('gpt-4o'))
  .withPrompt(
    IgniterAgentPrompt.create(`
      You are {{store}}'s personal shopping concierge.
      
      Guidelines:
      - Be helpful but never pushy
      - Always show prices clearly
      - Offer alternatives when items are out of stock
      - Suggest complementary products
    `)
  )
  .addToolset(shopToolset)
  .withMemory({
    provider: IgniterAgentInMemoryAdapter.create({ namespace: 'shop' }),
    working: { enabled: true, scope: 'session' },
    history: { enabled: true, limit: 200 },
    chats: { enabled: true },
  })
  .build()
```

***

## 5. Multi-Agent Workflow Orchestrator

A system that routes complex tasks through a chain of specialized agents.

```typescript
// Manager with 3 specialized agents
const orchestrator = IgniterAgentManager
  .create()
  .addAgent('researcher', researchAgent)
  .addAgent('writer', writerAgent)
  .addAgent('reviewer', reviewerAgent)
  .onAgentStart((name) => console.log(`✅ ${name} ready`))
  .onToolCallStart((agent, tool) => console.log(`[${agent}] → ${tool}`))
  .build()

await orchestrator.startAll()

// Orchestrate a research → write → review pipeline
async function runPipeline(topic: string) {
  // Phase 1: Research
  const researcher = orchestrator.get('researcher')
  const research = await researcher.generate({
    chatId: `pipeline_${Date.now()}`,
    userId: 'system',
    context: { topic },
    message: {
      role: 'user',
      content: `Research the topic: ${topic}. Gather key facts, data points, and perspectives.`,
    },
  })

  // Phase 2: Write based on research
  const writer = orchestrator.get('writer')
  const draft = await writer.generate({
    chatId: `pipeline_${Date.now()}`,
    userId: 'system',
    context: { research: research.content, topic },
    message: {
      role: 'user',
      content: `Write a comprehensive article on "${topic}" using this research:\n${research.content}`,
    },
  })

  // Phase 3: Review the draft
  const reviewer = orchestrator.get('reviewer')
  const review = await reviewer.generate({
    chatId: `pipeline_${Date.now()}`,
    userId: 'system',
    context: { draft: draft.content },
    message: {
      role: 'user',
      content: `Review this draft for accuracy, clarity, and completeness:\n${draft.content}`,
    },
  })

  return { research, draft, review }
}
```

***

## 6. DevOps Incident Responder

An agent that helps diagnose and resolve production incidents.

```typescript
const checkLogs = IgniterAgentTool
  .create('check_logs')
  .withDescription('Query application logs for error patterns')
  .withInput(
    z.object({
      service: z.string(),
      severity: z.enum(['error', 'warn']).default('error'),
      timeframe: z.string().default('15m'),
      limit: z.number().default(20),
    })
  )
  .withExecute(async ({ service, severity, timeframe, limit }) => {
    return logAggregator.query({ service, severity, timeframe, limit })
  })
  .build()

const checkMetrics = IgniterAgentTool
  .create('check_metrics')
  .withDescription('Query service metrics (CPU, memory, latency, error rate)')
  .withInput(z.object({ service: z.string(), metric: z.string().optional() }))
  .withExecute(async ({ service, metric }) => {
    return metricsService.query(service, metric)
  })
  .build()

const runDiagnostic = IgniterAgentTool
  .create('diagnose')
  .withDescription('Run a diagnostic check on a service')
  .withInput(z.object({ service: z.string(), check: z.string() }))
  .withExecute(async ({ service, check }) => {
    return diagnostics.run(service, check)
  })
  .build()

const devopsToolset = IgniterAgentToolset
  .create('devops')
  .addTool(checkLogs)
  .addTool(checkMetrics)
  .addTool(runDiagnostic)
  .build()

const incidentResponder = IgniterAgent
  .create('incident-responder')
  .withModel(openai('gpt-4o'))
  .withPrompt(
    IgniterAgentPrompt.create(`
      You are an on-call DevOps engineer responding to a production incident.
      
      Protocol:
      1. Check logs for error patterns
      2. Check service metrics for anomalies
      3. Run targeted diagnostics
      4. Provide a root cause analysis and remediation steps
      5. If you cannot determine the cause, recommend escalation
      
      Be concise and actionable. Every second matters during an incident.
    `)
  )
  .addToolset(devopsToolset)
  .onToolCallStart((agent, tool, input) => {
    incidentLog.info(`Running ${tool} with:`, input)
  })
  .build()
```


---

# Tools & Toolsets

> Create type-safe AI tools with Zod validation, group them into toolsets, and understand automatic error handling and result normalization.
URL: https://igniterjs.com/docs/agents/tools-toolsets

## Tools & Toolsets

Tools are the bridge between your AI agent and your application logic. Every tool has a name, description, typed input schema, and an execution handler. Toolsets group related tools by domain.

***

## Creating a Tool

### Tool Builder API

The `IgniterAgentTool` builder requires four things: a **name**, **description**, **input schema** (Zod), and **execute handler**.

```typescript
import { IgniterAgentTool } from '@igniter-js/agents'
import { z } from 'zod'

const greetTool = IgniterAgentTool
  .create('greet')
  .withDescription('Greet a user by name')
  .withInput(
    z.object({
      name: z.string().describe('The user name'),
      language: z.enum(['en', 'pt', 'es']).default('en'),
    })
  )
  .withExecute(async ({ name, language }) => {
    const greetings = { en: 'Hello', pt: 'Olá', es: 'Hola' }
    return `${greetings[language]}, ${name}!`
  })
  .build()
```

<Callout type="info">
  The **description** is critical — it's what the AI model uses to decide when to invoke your tool. Be specific about what the tool does and when to use it.
</Callout>

### Tool Builder Methods

| Method                   | Required | Description                                   |
| ------------------------ | -------- | --------------------------------------------- |
| `.create(name)`          | ✅        | Unique tool name within a toolset             |
| `.withDescription(text)` | ✅        | Human-readable description shown to the AI    |
| `.withInput(zodSchema)`  | ✅        | Zod schema defining input parameters          |
| `.withOutput(zodSchema)` | No       | Zod schema for output validation              |
| `.withExecute(handler)`  | ✅        | Async function that performs the tool's logic |
| `.build()`               | ✅        | Returns the built tool definition             |

### Execute Handler Signature

```typescript
type ExecuteHandler<TInput, TOutput> = (
  params: TInput,
  options: IgniterAgentToolExecuteOptions
) => Promise<TOutput>
```

The `params` object is **fully typed** — inferred from your Zod schema. The `options` object provides runtime context:

```typescript
interface IgniterAgentToolExecuteOptions {
  toolCallId: string
  messages: ModelMessage[]
  abortSignal?: AbortSignal
}
```

### Type Inference in Action

Every tool builder change updates the TypeScript types:

```typescript
const tool = IgniterAgentTool
  .create('search')             // IgniterAgentToolBuilder<'search', unknown, unknown>
  .withInput(z.object({         // ...<'search', { query: string, limit: number }, unknown>
    query: z.string(),
    limit: z.number().default(10),
  }))
  .withExecute(async (params) => {
    // params is typed: { query: string; limit: number }
    return { results: await search(params.query, params.limit) }
  })
  //                               ...<'search', ..., { results: string[] }>
  .build()
```

***

## Creating a Toolset

Toolsets group related tools under a namespace. When registered with an agent, each tool is prefixed with the toolset name: `{toolset}_{tool}`.

```typescript
import { IgniterAgentToolset } from '@igniter-js/agents'

const utilsToolset = IgniterAgentToolset
  .create('utils')
  .addTool(greetTool)
  .addTool(formatDateTool)
  .addTool(validateEmailTool)
  .build()

console.log(utilsToolset.name)   // 'utils'
console.log(utilsToolset.type)   // 'custom'
console.log(utilsToolset.status) // 'connected'
```

### Toolset Builder Methods

| Method            | Description                                      |
| ----------------- | ------------------------------------------------ |
| `.create(name)`   | Creates a new toolset builder with a unique name |
| `.withName(name)` | Renames the toolset during building              |
| `.addTool(tool)`  | Adds a built tool to the toolset                 |
| `.build()`        | Returns the built toolset                        |
| `.getName()`      | Returns the current toolset name                 |
| `.getTools()`     | Returns the current tools object                 |
| `.getToolCount()` | Returns the number of tools                      |

***

## Automatic Error Handling

Tools added to a toolset are **automatically wrapped** with error handling. The result is normalized into a consistent format:

```typescript
// Success result
{ success: true, data: <your return value> }

// Error result
{ success: false, error: "<error message>" }
```

This means you don't need try/catch in every tool — the framework handles it:

```typescript
const riskyTool = IgniterAgentTool
  .create('risky')
  .withDescription('A tool that might fail')
  .withInput(z.object({}))
  .withExecute(async () => {
    throw new Error('Something went wrong') // Caught automatically
  })
  .build()

// Will return { success: false, error: "Something went wrong" }
// The error is also logged via console.error
```

***

## Multiple Toolsets

Register multiple toolsets on a single agent — each creates a separate namespace:

```typescript
const githubToolset = IgniterAgentToolset
  .create('github')
  .addTool(createIssueTool)
  .addTool(listReposTool)
  .build()

const dockerToolset = IgniterAgentToolset
  .create('docker')
  .addTool(buildImageTool)
  .addTool(deployContainerTool)
  .build()

const agent = IgniterAgent
  .create('devops-bot')
  .withModel(openai('gpt-4o'))
  .addToolset(githubToolset)   // Tools: github_createIssue, github_listRepos
  .addToolset(dockerToolset)   // Tools: docker_buildImage, docker_deployContainer
  .build()
```

<Callout type="warn">
  Tool names must be unique **within** a toolset but can overlap **across** toolsets. The toolset prefix prevents collisions.
</Callout>

***

## Pattern: Reusable Tool Libraries

Extract common tools into shared modules for reuse across agents:

```typescript
// lib/tools/database.ts
import { IgniterAgentTool } from '@igniter-js/agents'
import { z } from 'zod'

export const queryDatabase = IgniterAgentTool
  .create('query')
  .withDescription('Execute a read-only SQL query')
  .withInput(
    z.object({
      sql: z.string().describe('SQL SELECT statement'),
      params: z.array(z.unknown()).optional(),
    })
  )
  .withExecute(async ({ sql, params }) => {
    return db.query(sql, params)
  })
  .build()

export const databaseToolset = IgniterAgentToolset
  .create('db')
  .addTool(queryDatabase)
  .build()
```

```typescript
// In any agent:
import { databaseToolset } from './lib/tools/database'

const agent = IgniterAgent
  .create('analyst')
  .withModel(openai('gpt-4o'))
  .addToolset(databaseToolset)
  .build()
```

***

## Next Steps

* [Prompts](/docs/agents/prompts) — Template-based system instructions
* [MCP Integration](/docs/agents/mcp-integration) — External tool providers via MCP
* [Best Practices](/docs/agents/best-practices) — Do's and Don'ts for tool design


---

# Troubleshooting

> Common errors, their causes, and solutions when working with @igniter-js/agents. Debugging tips for tools, MCP connections, memory, and multi-agent setups.
URL: https://igniterjs.com/docs/agents/troubleshooting

## Troubleshooting

Common issues and their solutions when building agents with `@igniter-js/agents`.

***

## Agent Start Failures

### Error: `AGENT_NOT_INITIALIZED`

```
IgniterAgentError: Agent 'support' is not registered
  code: AGENT_NOT_INITIALIZED
```

**Cause:** You're trying to access or start an agent that wasn't registered with the manager.

**Solution:** Register the agent with the manager before accessing it:

```typescript
const manager = IgniterAgentManager.create().build()

// Register first
manager.register('support', supportAgent)

// Then start
await manager.start('support')
```

### Error: `INVALID_CONFIG`

```
IgniterAgentConfigError: Tool name is required and must be a non-empty string
  code: INVALID_CONFIG
  field: name
```

**Cause:** A required configuration field is missing or invalid.

**Solution:** Check the `field` in the error metadata to identify what's missing:

```typescript
// Missing name
const tool = IgniterAgentTool.create('') // ❌ Empty string

// Missing description
const tool = IgniterAgentTool.create('myTool').build() // ❌ No description set

// Missing input schema
const tool = IgniterAgentTool
  .create('myTool')
  .withDescription('...')
  .build() // ❌ No input schema
```

***

## MCP Connection Issues

### Error: MCP connection hangs or times out

**Cause:** The MCP server process isn't starting or the remote server is unreachable.

**Solutions:**

1. **Test the MCP command manually:**

```bash
npx -y @modelcontextprotocol/server-filesystem /tmp
# Should start and wait for input
```

2. **Add verbose debugging:**

```typescript
const mcpClient = IgniterAgentMCPClient
  .create('filesystem')
  .withType('stdio')
  .withCommand('npx')
  .withArgs(['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])
  .withEnv({ DEBUG: 'mcp:*' })
  .build()
```

3. **Handle connection errors gracefully:**

```typescript
const agent = IgniterAgent.create('bot')
  .addMCP(mcpClient)
  .onMCPError((name, mcp, error) => {
    console.error(`MCP '${mcp}' failed:`, error.message)
  })
  .build()

try {
  await agent.start()
} catch (error) {
  if (error.message.includes('ECONNREFUSED')) {
    console.error('MCP server is not running. Start it first.')
  }
}
```

### Error: MCP tools not available

**Cause:** MCP tools are only discovered at `start()` time.

**Solution:** Always call `agent.start()` before `agent.generate()`:

```typescript
const agent = IgniterAgent.create('bot')
  .addMCP(filesystemMCP)
  .build()

await agent.start() // ← Required: discovers MCP tools

const result = await agent.generate({...}) // ← MCP tools now available
```

***

## Memory Issues

### Error: `MEMORY_PROVIDER_ERROR`

```
IgniterAgentMemoryError: saveMessage is not supported by the provider
  code: MEMORY_PROVIDER_ERROR
```

**Cause:** You're using a memory operation that the provider doesn't support.

**Solution:** Check the provider's supported methods. Not all providers implement every method. The in-memory adapter supports all methods; custom adapters may only implement a subset.

```typescript
// Check if method exists before calling
if (agent.memory) {
  try {
    await agent.memory.saveMessage({...})
  } catch (error) {
    if (error.code === 'MEMORY_PROVIDER_ERROR') {
      // Method not supported — log and continue
      console.warn('saveMessage not supported by this adapter')
    }
  }
}
```

### Issue: Memory lost on restart

**Cause:** Using `IgniterAgentInMemoryAdapter` in production.

**Solution:** Switch to `IgniterAgentJSONFileAdapter` for single-machine deployments or build a custom adapter for shared storage:

```typescript
// For single-machine production
import { IgniterAgentJSONFileAdapter } from '@igniter-js/agents'

const adapter = IgniterAgentJSONFileAdapter.create({
  filePath: './data/agent-memory.json',
})

// For multi-server: build a Redis adapter (see Memory docs)
```

***

## Tool Execution Issues

### Error: Tool returns `{ success: false, error: "..." }`

**Cause:** The tool threw an error during execution. This is normal — the framework wraps all tool calls with error handling.

**Solution:** The error is automatically captured. The AI will see the error response and can handle it accordingly:

```typescript
const tool = IgniterAgentTool
  .create('api_call')
  .withDescription('...')
  .withInput(z.object({ endpoint: z.string() }))
  .withExecute(async ({ endpoint }) => {
    const response = await fetch(endpoint)
    if (!response.ok) {
      throw new Error(`API returned ${response.status}: ${response.statusText}`)
    }
    return response.json()
  })
  .build()

// The AI will see:
// { success: false, error: "API returned 500: Internal Server Error" }
// And can respond to the user appropriately
```

### Error: Tool input validation fails

**Cause:** The Zod schema rejected the input values.

**Solution:** Check that your tool's Zod schema matches the expected input:

```typescript
// Schema expects 'userId' but code passes 'user_id'
.withInput(z.object({ userId: z.string() }))
//                                ^^ camelCase

// Calling with wrong key:
.withExecute(async ({ user_id }) => { // ❌ Should be userId
```

***

## TypeScript Issues

### Error: Type inference lost on builder

**Cause:** Breaking the type chain by assigning intermediate builders to loosely-typed variables.

**Solution:** Keep the builder chain intact or use explicit type annotations:

```typescript
// ❌ Loses type inference
let builder = IgniterAgent.create('bot')
builder = builder.withModel(openai('gpt-4o')) // Type narrowed incorrectly

// ✅ Chain directly
const agent = IgniterAgent
  .create('bot')
  .withModel(openai('gpt-4o'))
  .build()

// ✅ Use explicit type if you must break the chain
const builder: ReturnType<typeof IgniterAgent.create<'bot'>> = 
  IgniterAgent.create('bot')
```

### Error: `Property 'x' does not exist` on context

**Cause:** Context schema not set or mismatched.

**Solution:** Define a context schema for type-safe context:

```typescript
const agent = IgniterAgent.create('bot')
  .withContextSchema(z.object({ company: z.string() }))
  .build()

// Now context is typed:
await agent.generate({
  chatId: 'chat_001',
  userId: 'user_001',
  context: { company: 'Acme' }, // ✅ Typed
  message: { role: 'user', content: '...' },
})
```

***

## Logger/Debugging

### Enabling detailed logs

```typescript
import { IgniterLogger } from '@igniter-js/common'

const logger = IgniterLogger.create({ level: 'debug' })

const agent = IgniterAgent.create('bot')
  .withLogger(logger)
  .build()

// Now see: debug → IgniterAgent.start started { agent: 'bot', ... }
//          success → IgniterAgent.start success { durationMs: 342 }
//          error → IgniterAgent.mcp.connect failed Error(...)
```

### Debugging tool calls

```typescript
const agent = IgniterAgent.create('bot')
  .onToolCallStart((agent, tool, input) => {
    console.log(`[DEBUG] ${agent} → ${tool}`, input)
  })
  .onToolCallEnd((agent, tool, output) => {
    console.log(`[DEBUG] ${agent} ← ${tool}`, output)
  })
  .onToolCallError((agent, tool, error) => {
    console.error(`[DEBUG] ${agent} ✕ ${tool}`, error)
  })
  .build()
```

***

## Browser Import Protection

### Error: `@igniter-js/agents is server-only`

**Cause:** Importing agents in a browser/Vite/Next.js client component.

**Solution:** Agents is server-only. Use it only in:

* API routes (`app/api/**/route.ts` in Next.js)
* Server actions
* `getServerSideProps` / server components
* CLI tools
* Background workers
* Express/Fastify route handlers

```typescript
// ✅ OK: API route
// app/api/chat/route.ts
import { IgniterAgent } from '@igniter-js/agents'

// ❌ Wrong: Client component
// components/Chat.tsx
import { IgniterAgent } from '@igniter-js/agents' // Will throw!
```

***

## Quick Diagnosis Checklist

* [ ] Is `agent.start()` called before `agent.generate()`?
* [ ] Are MCP servers reachable (test manually)?
* [ ] Is the model provider API key set as an environment variable?
* [ ] Are tool names unique within each toolset?
* [ ] Are tool descriptions specific and actionable?
* [ ] Is context schema set if using typed context?
* [ ] Is the memory adapter appropriate for the deployment (in-memory vs persistent)?
* [ ] Are Node.js >= 22 or Bun >= 1.0 in use?
* [ ] Is `@ai-sdk/openai` (or your provider) installed?
* [ ] Is `zod` installed (peer dependency)?


---

# Platform Adapters

> Configure and use Telegram, WhatsApp, and Discord adapters. Capability comparison, configuration reference, and platform-specific features.
URL: https://igniterjs.com/docs/bots/adapters

## Platform Adapters

Adapters translate between platform-specific APIs and the normalized `BotContext`. This page covers the three first-party adapters in detail.

***

## Telegram Adapter

The Telegram adapter supports the **full Bot API surface** — webhooks, long polling, commands, inline keyboards, and all content types.

### Configuration

```typescript
import { telegram } from '@igniter-js/bot';

const tg = telegram({
  token: '123456:ABC-DEF...',
  handle: '@your_bot', // Optional: overrides global handle
  webhook: {
    url: 'https://your-domain.com/api/bot/telegram',
    secret: 'my-webhook-secret', // Optional: validates webhook authenticity
    dropPendingUpdates: true,     // Clear pending updates on restart (default: true)
  },
});
```

| Parameter                    | Type      | Required | Default                       | Description                         |
| ---------------------------- | --------- | -------- | ----------------------------- | ----------------------------------- |
| `token`                      | `string`  | ✅        | `TELEGRAM_TOKEN` env          | Bot API token from @BotFather       |
| `handle`                     | `string`  | ❌        | Global bot handle             | Bot @username for mention detection |
| `webhook.url`                | `string`  | ❌        | `TELEGRAM_WEBHOOK_URL` env    | Public HTTPS endpoint               |
| `webhook.secret`             | `string`  | ❌        | `TELEGRAM_WEBHOOK_SECRET` env | Validates webhook authenticity      |
| `webhook.dropPendingUpdates` | `boolean` | ❌        | `true`                        | Clear pending updates on init       |

### Initialization

During `.start()`, the Telegram adapter:

1. Deletes any existing webhook
2. Registers bot commands via `setMyCommands`
3. Sets the new webhook with the configured URL and secret

If no `webhook.url` is provided, the adapter skips webhook setup and logs a warning — you can use long polling instead.

### Inline Keyboards

Telegram supports both inline keyboards (within messages) and reply keyboards (below input):

```typescript
// Inline keyboard (buttons inside the message)
async handle(ctx) {
  await ctx.replyWithButtons('Choose an option:', [
    [
      { id: 'buy', label: '🛒 Buy Now', action: 'url', data: { url: 'https://shop.com' } },
      { id: 'info', label: 'ℹ️ More Info', action: 'callback', data: 'more_info' },
    ],
    [
      { id: 'share', label: '📤 Share', action: 'share', data: '' },
    ],
  ]);
}
```

### Send Methods

All content types are supported:

```typescript
// Text
await ctx.reply('Hello!');

// Image
await ctx.replyWithImage('https://example.com/photo.jpg', 'Check this out!');

// Document
await ctx.replyWithDocument(file, 'report.pdf');

// Location
await ctx.bot.send({
  provider: 'telegram',
  channel: ctx.channel.id,
  content: {
    type: 'location',
    latitude: 40.7128,
    longitude: -74.0060,
    name: 'New York City',
  },
});

// Poll
await ctx.bot.send({
  provider: 'telegram',
  channel: ctx.channel.id,
  content: {
    type: 'poll',
    question: 'What is your favorite language?',
    options: ['TypeScript', 'Rust', 'Go', 'Python'],
    isAnonymous: true,
  },
});

// Interactive with inline keyboard
await ctx.replyWithButtons('Confirm?', [
  { id: 'yes', label: '✅ Yes', action: 'callback', data: 'confirm_yes' },
  { id: 'no', label: '❌ No', action: 'callback', data: 'confirm_no' },
]);
```

### Actions

```typescript
// Edit message
await ctx.editMessage!('12345', { type: 'text', content: 'Updated!' });

// Delete message
await ctx.deleteMessage!('12345');

// Typing indicator
await ctx.sendTyping!();
```

<Callout type="info">
  Telegram does **not** support message reactions via the Bot API, so `ctx.react()` is not available.
</Callout>

***

## WhatsApp Adapter

The WhatsApp adapter works with the **Meta WhatsApp Cloud API**. It supports text, media, interactive buttons, and location/contact sharing.

### Configuration

```typescript
import { whatsapp } from '@igniter-js/bot';

const wa = whatsapp({
  token: 'EAAx...',            // Cloud API access token
  phone: '1234567890',         // Phone number ID
});
```

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `token`   | `string` | ✅        | WhatsApp Cloud API access token   |
| `phone`   | `string` | ✅        | WhatsApp Business phone number ID |

<Callout type="warn">
  WhatsApp webhook setup is managed through the **Meta Developer Dashboard**, not the adapter's `init()` method. The `init()` call is a no-op that logs a confirmation message.
</Callout>

### Interactive Buttons (max 3)

WhatsApp limits interactive messages to 3 buttons:

```typescript
async handle(ctx) {
  await ctx.replyWithButtons('Confirm your order:', [
    { id: 'confirm', label: '✅ Confirm', action: 'callback', data: 'order_confirm' },
    { id: 'cancel', label: '❌ Cancel', action: 'callback', data: 'order_cancel' },
    { id: 'help', label: '🆘 Help', action: 'callback', data: 'order_help' },
  ]);
}
```

The adapter automatically converts buttons to the WhatsApp interactive message format.

### Media Handling

WhatsApp requires media URLs. The adapter handles File objects by converting them to data URLs:

```typescript
// URL (preferred for production)
await ctx.replyWithImage('https://cdn.example.com/product.jpg', 'New arrival!');

// File object (converted to data URL — works for small files)
const file = new File([buffer], 'receipt.pdf', { type: 'application/pdf' });
await ctx.replyWithDocument(file, 'Your receipt');
```

### Platform Limitations

WhatsApp does **not** support:

* Editing or deleting messages via the Cloud API
* Polls
* Traditional slash commands (commands are parsed from message text by the framework)
* Message pinning

***

## Discord Adapter

The Discord adapter uses the **Interactions API** for slash commands, buttons, and select menus. It includes signature verification for webhook security.

### Configuration

```typescript
import { discord } from '@igniter-js/bot';

const dc = discord({
  token: 'MTIz...',                     // Bot token
  applicationId: '123456789012345678',   // Application ID
  publicKey: 'abc123...',                // Public key for signature verification
});
```

| Parameter       | Type     | Required | Description                                              |
| --------------- | -------- | -------- | -------------------------------------------------------- |
| `token`         | `string` | ✅        | Discord bot token                                        |
| `applicationId` | `string` | ❌        | Application ID (required for slash command registration) |
| `publicKey`     | `string` | ❌        | Public key for Ed25519 signature verification            |

### Signature Verification

The Discord adapter validates interaction signatures using Ed25519. If `publicKey` is configured, every incoming interaction is verified before processing. Requests with invalid signatures receive a `401 Unauthorized` response.

### Slash Commands

Commands are automatically registered as Discord slash commands during `init()`:

```typescript
// This command becomes a Discord slash command
builder.addCommand('ping', {
  name: 'ping',
  aliases: [],
  description: 'Check latency', // Used as slash command description
  help: 'Use /ping to check bot responsiveness',
  async handle(ctx) {
    await ctx.reply('🏓 Pong!');
  },
});
```

### Message Components (Buttons & Select Menus)

Discord supports up to **5 buttons per row** and **5 rows per message**:

```typescript
async handle(ctx) {
  await ctx.replyWithButtons('Select an action:', [
    [
      { id: 'primary', label: 'Primary', action: 'callback', data: 'action_primary' },
      { id: 'secondary', label: 'Secondary', action: 'callback', data: 'action_secondary' },
    ],
    [
      { id: 'docs', label: '📚 Documentation', action: 'url', data: { url: 'https://docs.example.com' } },
    ],
  ]);
}
```

### Thread Support

Discord supports threads natively. The adapter detects thread context and routes messages accordingly.

### Embeds

For image URLs, the adapter automatically creates Discord embeds:

```typescript
await ctx.replyWithImage('https://example.com/photo.jpg', 'A beautiful photo');
// Creates an embed with the image, not a plain URL
```

***

## Adapter Client

Every adapter exposes a pre-configured HTTP client for making direct API calls:

```typescript
const bot = IgniterBot.create()
  .addAdapter('telegram', tg)
  .build();

// Get the adapter's client
const tgAdapter = bot.getAdapter('telegram');
const client = tgAdapter?.client;

if (client) {
  // Direct Telegram API calls
  const me = await client.get('/getMe');
  const chat = await client.post('/getChat', { chat_id: '123456' });

  // Raw Discord API calls
  const guild = await client.get('/guilds/123456789');
}
```

The client is pre-configured with the platform's base URL, authentication headers, and content type negotiation. All methods return typed responses.

***

## Custom Adapters

You can build adapters for any chat platform. See the `Bot.adapter()` static method:

```typescript
const myAdapter = Bot.adapter({
  name: 'my-platform',
  parameters: z.object({
    apiKey: z.string(),
    endpoint: z.string().url(),
  }),
  capabilities: {
    content: { text: true, image: false, /* ... */ },
    actions: { edit: false, delete: false, /* ... */ },
    features: { webhooks: true, /* ... */ },
    limits: { maxMessageLength: 1000, maxFileSize: 10 * 1024 * 1024, maxButtonsPerMessage: 3 },
  },
  init: async ({ config, commands, logger }) => {
    // Setup webhook, register commands, etc.
  },
  handle: async ({ request, config, logger }) => {
    // Parse request → return BotContext or null
    const body = await request.json();
    return {
      event: 'message',
      provider: 'my-platform',
      channel: { id: body.chat_id, name: 'Chat', isGroup: false },
      message: {
        author: { id: body.user_id, name: body.user_name, username: body.user_handle },
        content: { type: 'text', content: body.text, raw: body.text },
        isMentioned: body.text.includes('@mybot'),
      },
    };
  },
  sendText: async ({ channel, text, config }) => {
    // Send text message to platform API
    await fetch(config.endpoint + '/messages', {
      method: 'POST',
      headers: { Authorization: `Bearer ${config.apiKey}` },
      body: JSON.stringify({ chat_id: channel, text }),
    });
  },
});
```

Custom adapters automatically integrate with the entire middleware, plugin, session, and event system — no extra wiring needed.

***

## Next Steps

<Cards>
  <Card title="Middlewares" description="Add auth, rate-limiting, and logging to your bot." href="/docs/bots/middlewares" />

  <Card title="Framework Integration" description="Wire up your bot with Next.js, Express, Fastify, and more." href="/docs/bots/framework-integration" />

  <Card title="API Reference" description="Complete API documentation for all classes and methods." href="/docs/bots/api-reference" />
</Cards>


---

# API Reference

> Complete API reference for @igniter-js/bot. Builder methods, Bot class, adapters, middlewares, plugins, types, and error codes.
URL: https://igniterjs.com/docs/bots/api-reference

## API Reference

This page documents every public API surface of `@igniter-js/bot`. All methods, types, and exports are listed with their signatures and descriptions.

***

## IgniterBotBuilder

The main entry point for constructing bots.

### Static Methods

#### `IgniterBot.create()`

Creates a new builder instance.

```typescript
static create(): IgniterBotBuilder
```

### Identity Methods

#### `withHandle(handle: string): this`

Sets the bot handle (e.g., `@mybot`). Auto-generates `id` and `name` from the handle if not set explicitly.

```typescript
withHandle(handle: string): this
```

#### `withId(id: string): this`

Sets a unique bot identifier. Optional — derived from handle if not provided.

```typescript
withId(id: string): this
```

#### `withName(name: string): this`

Sets a human-readable display name. Optional — derived from handle if not provided.

```typescript
withName(name: string): this
```

### Configuration Methods

#### `withLogger(logger: BotLogger): this`

Configures a structured logger for the bot and all adapters.

```typescript
withLogger(logger: BotLogger): this
```

The `BotLogger` interface:

```typescript
interface BotLogger {
  debug?: (...args: any[]) => void
  info?: (...args: any[]) => void
  warn?: (...args: any[]) => void
  error?: (...args: any[]) => void
}
```

#### `withSessionStore(store: BotSessionStore): this`

Configures session storage for conversational state.

```typescript
withSessionStore(store: BotSessionStore): this
```

#### `withOptions(options: BotOptions): this`

Sets advanced bot options.

```typescript
withOptions(options: BotOptions): this

interface BotOptions {
  timeout?: number                      // Request timeout in ms
  retries?: number                      // Retry attempts for failed operations
  autoRegisterCommands?: boolean        // Auto-register with platforms
  errorHandler?: (error: BotError, context?: BotContext) => void | Promise<void>
}
```

### Adapter Methods

#### `addAdapter(key: string, adapter: IBotAdapter): IgniterBotBuilder`

Adds a single platform adapter. Returns a new builder with updated generic types.

```typescript
addAdapter<K extends string, A extends IBotAdapter<any>>(
  key: K,
  adapter: A
): IgniterBotBuilder<TAdapters & Record<K, A>, TCommands, TContext>
```

#### `addAdapters(adapters: Record<string, IBotAdapter>): IgniterBotBuilder`

Adds multiple adapters at once.

```typescript
addAdapters<A extends Record<string, IBotAdapter<any>>>(
  adapters: A
): IgniterBotBuilder<TAdapters & A, TCommands, TContext>
```

### Command Methods

#### `addCommand(name: string, command: BotCommand): IgniterBotBuilder`

Registers a command. Returns a new builder with updated types.

```typescript
addCommand<K extends string, C extends BotCommand<TContext>>(
  name: K,
  command: C
): IgniterBotBuilder<TAdapters, TCommands & Record<K, C>, TContext>
```

#### `addCommands(commands: Record<string, BotCommand>): IgniterBotBuilder`

Registers multiple commands at once.

```typescript
addCommands<C extends Record<string, BotCommand<TContext>>>(
  commands: C
): IgniterBotBuilder<TAdapters, TCommands & C, TContext>
```

#### `addCommandGroup(prefix: string, commands: Record<string, BotCommand>): IgniterBotBuilder`

Registers prefixed commands (e.g., `admin_ban`, `admin_kick`).

```typescript
addCommandGroup<C extends Record<string, BotCommand<TContext>>>(
  prefix: string,
  commands: C
): IgniterBotBuilder<TAdapters, TCommands, TContext>
```

### Middleware Methods

#### `addMiddleware(middleware: Middleware): IgniterBotBuilder`

Adds a middleware to the pipeline.

```typescript
addMiddleware<TContextAdditions>(
  middleware: Middleware<TContext, TContextAdditions>
): IgniterBotBuilder<TAdapters, TCommands, TContext & Awaited<TContextAdditions>>
```

#### `addMiddlewares(middlewares: Middleware[]): this`

Adds multiple middlewares at once.

```typescript
addMiddlewares(middlewares: Middleware<TContext, any>[]): this
```

### Plugin Methods

#### `usePlugin(plugin: BotPlugin): this`

Loads a plugin, registering all its commands, middlewares, adapters, and hooks.

```typescript
usePlugin(plugin: BotPlugin): this
```

### Event Listener Methods

#### `onMessage(handler: BotEventHandler): this`

Registers a message event listener.

```typescript
onMessage(handler: BotEventHandler<TContext>): this

type BotEventHandler<TContext> = (ctx: TContext) => Promise<void> | void
```

#### `onError(handler: BotErrorHandler): this`

Registers an error event listener.

```typescript
onError(handler: BotErrorHandler<TContext>): this

type BotErrorHandler<TContext> = (
  ctx: TContext & { error: BotError },
) => Promise<void> | void
```

#### `onCommand(handler: BotEventHandler): this`

Registers a command event listener (called for all commands).

```typescript
onCommand(handler: BotEventHandler<TContext>): this
```

#### `onStart(handler: BotStartHandler): this`

Registers a startup hook.

```typescript
onStart(handler: BotStartHandler): this

type BotStartHandler = () => Promise<void> | void
```

### Build Method

#### `build(): Bot`

Validates configuration and returns the immutable Bot instance.

```typescript
build(): Bot<TAdapters, Middleware<TContext, any>[], TCommands>
```

Throws if:

* No adapters are registered
* No handle is configured (neither global nor in any adapter)

***

## Bot Class

The runtime bot instance. Returned by `builder.build()`.

### Properties

| Property    | Type                  | Description           |
| ----------- | --------------------- | --------------------- |
| `id`        | `string`              | Unique bot identifier |
| `name`      | `string`              | Display name          |
| `botHandle` | `string \| undefined` | Global handle         |

### Methods

#### `start(): Promise<void>`

Initializes all adapters (registers webhooks, commands, etc.) and runs startup hooks.

```typescript
async start(): Promise<void>
```

#### `handle(provider: string, request: Request): Promise<Response>`

Routes an incoming request to the appropriate adapter.

```typescript
async handle(provider: string, request: Request): Promise<Response>
```

Throws `BotError` with code `PROVIDER_NOT_FOUND` if the adapter isn't registered.

#### `send(params: BotSendParams): Promise<void>`

Sends an outbound message through a specific adapter.

```typescript
async send(params: BotSendParams): Promise<void>

type BotSendParams<TConfig> = {
  provider: string
  channel: string
  content: BotOutboundContent
  options?: BotSendOptions
  config: TConfig
}
```

Throws `BotError` with code `CONTENT_TYPE_NOT_SUPPORTED` if the adapter doesn't support the content type.

#### `on(event: BotEvent, callback: Function): void`

Registers a runtime event listener.

```typescript
on(event: BotEvent, callback: (ctx: BotContext) => Promise<void>): void

type BotEvent = 'start' | 'message' | 'error'
```

#### `registerCommand(name: string, command: BotCommand): this`

Dynamically registers a command at runtime.

```typescript
registerCommand(name: string, command: BotCommand): this
```

#### `registerAdapter(key: string, adapter: IBotAdapter): this`

Dynamically registers an adapter at runtime.

```typescript
registerAdapter<K extends string, A extends IBotAdapter<any>>(key: K, adapter: A): this
```

#### `use(middleware: Middleware): this`

Dynamically adds a middleware at runtime.

```typescript
use(mw: Middleware<any, any>): this
```

#### `onPreProcess(hook: Function): this`

Registers a hook that runs before the middleware pipeline (for session loading, context enrichment).

```typescript
onPreProcess(hook: (ctx: BotContext) => Promise<void> | void): this
```

#### `onPostProcess(hook: Function): this`

Registers a hook that runs after successful processing.

```typescript
onPostProcess(hook: (ctx: BotContext) => Promise<void> | void): this
```

#### `emit(event: BotEvent, ctx: BotContext): Promise<void>`

Manually emits an event to registered listeners.

```typescript
async emit(event: BotEvent, ctx: BotContext): Promise<void>
```

#### `getAdapter(provider: string): IBotAdapter | undefined`

Returns the adapter for a specific provider.

```typescript
getAdapter(provider: string): IBotAdapter<any> | undefined
```

#### `getAdapters(): Record<string, IBotAdapter>`

Returns all registered adapters.

```typescript
getAdapters(): Record<string, IBotAdapter<any>>
```

### Static Methods

#### `Bot.adapter(config): AdapterFactory`

Creates a typed adapter factory. Used internally by built-in adapters and for custom adapters.

```typescript
static adapter<TConfig extends ZodObject<any>>(config: {
  name: string
  parameters: TConfig
  capabilities: BotAdapterCapabilities
  verify?: (params: AdapterVerifyParams) => Promise<Response | null>
  init: (params: AdapterInitParams) => Promise<void>
  handle: (params: AdapterHandleParams) => Promise<Omit<BotContext, 'bot' | 'session' | ...> | null>
  sendTyping?: (params: AdapterSendTypingParams) => Promise<void>
  client?: (config, logger?) => AdapterClient
  sendText?: (params: AdapterSendTextParams) => Promise<void>
  sendImage?: (params: AdapterSendImageParams) => Promise<void>
  // ... all send methods, editMessage, deleteMessage
}): (config?: Partial<TypeOf<TConfig>>) => IBotAdapter<TConfig>
```

#### `Bot.command(command): BotCommand`

Validates and returns a command definition.

```typescript
static command<TContext, TContextAdditions>(
  command: BotCommand<TContext, TContextAdditions>
): BotCommand<TContext, TContextAdditions>
```

#### `Bot.middleware(middleware): Middleware`

Validates and returns a middleware function.

```typescript
static middleware<TContext, TContextAdditions>(
  middleware: Middleware<TContext, TContextAdditions>
): Middleware<TContext, TContextAdditions>
```

#### `Bot.create(config): Bot`

Internal factory. **Deprecated:** Use `IgniterBot` builder instead.

```typescript
static create<TAdapters, TMiddlewares, TCommands>(config: {
  id: string
  name: string
  handle?: string
  adapters: TAdapters
  middlewares?: TMiddlewares
  commands?: TCommands
  on?: Partial<Record<BotEvent, (ctx: BotContext) => Promise<void>>>
  logger?: BotLogger
  sessionStore?: BotSessionStore
}): Bot<TAdapters, TMiddlewares, TCommands>
```

***

## BotCommand Interface

```typescript
interface BotCommand<TContext = BotContext, TArgs = any> {
  name: string
  aliases: string[]
  description: string
  help: string
  args?: ZodType<TArgs>
  handle: (ctx: TContext, params: TArgs) => Promise<void>
  subcommands?: Record<string, Omit<BotCommand<TContext>, 'name' | 'aliases'>>
}
```

***

## BotContext Interface

```typescript
interface BotContext {
  event: BotEvent                               // 'start' | 'message' | 'error'
  provider: string                               // 'telegram' | 'whatsapp' | 'discord'

  bot: {
    id: string
    name: string
    send: (params: Omit<BotSendParams<any>, 'config'>) => Promise<void>
    getAdapter?: (provider: string) => IBotAdapter | undefined
    getAdapters?: () => Record<string, IBotAdapter>
  }

  channel: {
    id: string
    name: string
    isGroup: boolean
  }

  message: {
    id?: string
    content?: BotContent
    attachments?: BotAttachmentContent[]
    author: {
      id: string
      name: string
      username: string
    }
    isMentioned: boolean
  }

  session: BotSessionHelper

  reply(content: BotOutboundContent | string, options?: BotSendOptions): Promise<void>
  replyWithButtons(text: string, buttons: BotButton[], options?: BotSendOptions): Promise<void>
  replyWithImage(image: string | File, caption?: string, options?: BotSendOptions): Promise<void>
  replyWithDocument(file: File, caption?: string, options?: BotSendOptions): Promise<void>
  editMessage?(messageId: string, content: BotOutboundContent): Promise<void>
  deleteMessage?(messageId: string): Promise<void>
  react?(emoji: string, messageId?: string): Promise<void>
  sendTyping?(): Promise<void>
}
```

***

## Content Types

### BotOutboundContent (Send)

```typescript
type BotOutboundContent =
  | BotTextContent        // { type: 'text', content: string }
  | BotImageContent       // { type: 'image', content: string, file?: File, caption?: string }
  | BotVideoContent       // { type: 'video', content: string, file?: File, caption?: string }
  | BotAudioContent       // { type: 'audio', content: string, file?: File }
  | BotDocumentContent    // { type: 'document', content: string, file: File, filename?: string, caption?: string }
  | BotStickerContent     // { type: 'sticker', content: string, file?: File }
  | BotLocationContent    // { type: 'location', latitude: number, longitude: number, name?: string, address?: string }
  | BotContactContent     // { type: 'contact', phoneNumber: string, firstName: string, lastName?: string }
  | BotPollContent        // { type: 'poll', question: string, options: string[], ... }
  | BotInteractiveContent // { type: 'interactive', text: string, buttons?: BotButton[], inlineKeyboard?: BotInlineKeyboardRow[] }
  | BotReplyContent       // { type: 'reply', messageId: string, content: BotOutboundContent }
```

### BotSendOptions

```typescript
interface BotSendOptions {
  replyToMessageId?: string
  disableWebPagePreview?: boolean
  disableNotification?: boolean
  parseMode?: 'HTML' | 'Markdown' | 'MarkdownV2'
  protectContent?: boolean
  autoFormat?: boolean
}
```

***

## BotError

```typescript
class BotError extends Error {
  code: BotErrorCode
  meta?: Record<string, unknown>

  constructor(code: BotErrorCode, message?: string, meta?: Record<string, unknown>)
}

type BotErrorCode =
  | 'CLIENT_NOT_PROVIDED'
  | 'PROVIDER_NOT_FOUND'
  | 'COMMAND_NOT_FOUND'
  | 'INVALID_COMMAND_PARAMETERS'
  | 'ADAPTER_HANDLE_RETURNED_NULL'
  | 'CONTENT_TYPE_NOT_SUPPORTED'
  | 'INVALID_CONTENT'
```

***

## Session Interfaces

### BotSessionStore

```typescript
interface BotSessionStore {
  get(userId: string, channelId: string): Promise<BotSession | null>
  set(userId: string, channelId: string, session: BotSession): Promise<void>
  delete(userId: string, channelId: string): Promise<void>
  clear(userId: string): Promise<void>
}
```

### BotSessionHelper

```typescript
interface BotSessionHelper extends BotSession {
  save(): Promise<void>
  delete(): Promise<void>
  update(data: Partial<Record<string, any>>): Promise<void>
}
```

***

## Plugin Interface

```typescript
interface BotPlugin {
  name: string
  version: string
  description?: string
  commands?: Record<string, BotCommand>
  middlewares?: Middleware<any, any>[]
  adapters?: Record<string, IBotAdapter<any>>
  hooks?: {
    onStart?: () => Promise<void> | void
    onMessage?: (ctx: BotContext) => Promise<void> | void
    onError?: (ctx: BotContext & { error: BotError }) => Promise<void> | void
    onStop?: () => Promise<void> | void
  }
  config?: Record<string, any>
}
```

***

## Exports

### Main Exports

```typescript
export { IgniterBot, IgniterBotBuilder } from './builder'
export { Bot, BotError, BotErrorCodes } from './bot.provider'
export { telegram } from './adapters/telegram'
export { whatsapp } from './adapters/whatsapp'
export { discord } from './adapters/discord'
export { nextRouteHandlerAdapter } from './adapters/nextjs'
export { tanstackStartRouteHandlerAdapter } from './adapters/tanstack-start'
export { adapters } from './index' // Convenience: { telegram, whatsapp, discord }
export { VERSION } from './index'

// Middlewares
export { authMiddleware, authPresets, roleMiddleware } from './middlewares/auth'
export { rateLimitMiddleware, rateLimitPresets, memoryRateLimitStore } from './middlewares/rate-limit'
export { loggingMiddleware, loggingPresets, commandLoggingMiddleware } from './middlewares/logging'

// Plugins
export { analyticsPlugin } from './plugins/analytics'

// Stores
export { memoryStore, MemorySessionStore } from './stores/memory'
```

***

## Next Steps

<Cards>
  <Card title="Best Practices" description="Production patterns, security tips, and anti-patterns to avoid." href="/docs/bots/best-practices" />

  <Card title="Troubleshooting" description="Common errors, debugging techniques, and solutions." href="/docs/bots/troubleshooting" />

  <Card title="Real-World Examples" description="Complete production bot scenarios with code." href="/docs/bots/real-world" />
</Cards>


---

# Best Practices

> Production patterns, security tips, and anti-patterns for building bots with @igniter-js/bot. Keep your code maintainable, secure, and performant.
URL: https://igniterjs.com/docs/bots/best-practices

## Best Practices

This page captures patterns that work well (and pitfalls to avoid) when building production bots with `@igniter-js/bot`.

***

## Architecture & Organization

### ✅ Do: Keep Bot Configuration in a Single File

```typescript
// lib/bot.ts — Single source of truth for your bot
import { IgniterBot, telegram, whatsapp, memoryStore } from '@igniter-js/bot';
import { commands } from './commands';
import { middlewares } from './middlewares';
import { plugins } from './plugins';

export const bot = IgniterBot.create()
  .withHandle('@mybot')
  .withSessionStore(memoryStore())
  .addAdapters({ telegram: telegram({ token: env.TELEGRAM_TOKEN }) })
  .addCommands(commands)
  .addMiddlewares(middlewares)
  .build();
```

### ❌ Don't: Scatter Bot Configuration Across Multiple Files

Avoid building different parts of the bot in separate modules and merging them later — the builder pattern is designed for one clear configuration path.

### ✅ Do: Extract Commands into Separate Files

```typescript
// commands/start.ts
import { Bot } from '@igniter-js/bot';

export const startCommand = Bot.command({
  name: 'start',
  aliases: ['hello'],
  description: 'Greets the user',
  help: 'Use /start to receive a welcome',
  async handle(ctx) {
    await ctx.reply('Welcome!');
  },
});

// commands/index.ts
export { startCommand } from './start';
export { helpCommand } from './help';
export { searchCommand } from './search';

// lib/bot.ts
import * as commands from './commands';
builder.addCommands(commands);
```

### ✅ Do: Isolate Business Logic from Command Handlers

```typescript
// services/search.service.ts — Pure business logic, testable
export async function searchCatalog(query: string, category?: string) {
  // Database queries, API calls, etc.
  return results;
}

// commands/search.ts — Thin handler, delegates to service
import { searchCatalog } from '../services/search.service';

export const searchCommand = Bot.command({
  name: 'search',
  aliases: ['find'],
  description: 'Search the catalog',
  help: 'Use /search &lt;query&gt;',
  async handle(ctx) {
    const results = await searchCatalog(ctx.args.query);
    await ctx.reply(formatResults(results)); // Separate formatting
  },
});
```

***

## Middleware Ordering

### ✅ Do: Order Middlewares by Criticality

```
1. Logging (outside timing)
2. Rate limiting (protect resources)
3. Authentication (block unauthorized)
4. Context enrichment (load user data)
5. Business logic middlewares
```

### ❌ Don't: Place Auth After Business Logic

```
// BAD: Rate limiting won't apply to unauthorized users
builder
  .addMiddleware(authMiddleware({ ... }))     // 1st
  .addMiddleware(rateLimitMiddleware({ ... })) // 2nd — useless if auth blocks

// GOOD: Rate limit first
builder
  .addMiddleware(rateLimitMiddleware({ ... }))  // 1st: always runs
  .addMiddleware(authMiddleware({ ... }))       // 2nd
```

***

## Sessions

### ✅ Do: Use Session Update for Partial Changes

```typescript
// GOOD: Merge — other session data is preserved
await ctx.session.update({ step: 'checkout' });

// BAD: Direct mutation might not save
ctx.session.data.step = 'checkout'; // May not persist
```

### ✅ Do: Clear Sessions When Flows Complete

```typescript
async handle(ctx) {
  if (ctx.session.data.step === 'complete') {
    await saveData(ctx.session.data);
    await ctx.session.delete(); // Clean up
    await ctx.reply('All done! 🎉');
  }
}
```

### ❌ Don't: Store Large Objects in Sessions

```typescript
// BAD: Sessions are for conversational state, not data storage
await ctx.session.update({ allProducts: hugeProductArray });

// GOOD: Store IDs, fetch data when needed
await ctx.session.update({ lastSearchQuery: query });
```

***

## Error Handling

### ✅ Do: Always Have a Global Error Handler

```typescript
builder.onError(async (ctx) => {
  console.error(`[${ctx.provider}] Error for user ${ctx.message.author.id}:`, ctx.error);

  // Don't reveal internal details to users
  await ctx.reply('⚠️ Something went wrong. Our team has been notified.');
});
```

### ✅ Do: Use try/catch in Individual Handlers for Recoverable Errors

```typescript
async handle(ctx) {
  try {
    const data = await externalApi.fetch();
    await ctx.reply(formatData(data));
  } catch (error) {
    await ctx.reply('⚠️ Could not fetch data. Please try again.');
    // Don't re-throw — it was handled gracefully
  }
}
```

### ❌ Don't: Expose Internal Error Details to Users

```typescript
// BAD: Leaks internal structure
await ctx.reply(`Error: ${error.message}\nStack: ${error.stack}`);

// GOOD: User-friendly message
await ctx.reply('Something went wrong. Try again or contact support.');
```

***

## Security

### ✅ Do: Validate All User Input

```typescript
// Zod validation at the command level
args: z.object({
  userId: z.string().regex(/^[a-zA-Z0-9_-]+$/), // Sanitized
  amount: z.number().int().positive().max(10000),
})
```

### ✅ Do: Use Environment Variables for Secrets

```typescript
// GOOD
telegram({ token: process.env.TELEGRAM_TOKEN! })

// BAD: Never hardcode tokens
telegram({ token: '123456:ABC' })
```

### ✅ Do: Verify Webhook Signatures

```typescript
// Discord adapter does this automatically if publicKey is set
discord({
  token: '...',
  publicKey: process.env.DISCORD_PUBLIC_KEY!,
})
```

### ❌ Don't: Trust `ctx.message.author.id` Without Verification

The adapter parses this from the platform — it's trustworthy for platform IDs, but don't use it directly for authorization without additional checks (database lookup, subscription status).

***

## Performance

### ✅ Do: Initialize Bot at Module Level

```typescript
// GOOD: Created once on import, reused across requests
export const bot = IgniterBot.create() /* ... */ .build();

// BAD: Created per-request (serverless cold start only)
export function getBot() {
  return IgniterBot.create() /* ... */ .build();
}
```

### ✅ Do: Batch Database Queries in Middleware

```typescript
// Enrich context once, use everywhere
builder.addMiddleware(async (ctx, next) => {
  const [user, preferences, permissions] = await Promise.all([
    db.users.findById(ctx.message.author.id),
    db.preferences.get(ctx.message.author.id),
    db.permissions.get(ctx.message.author.id),
  ]);
  await next();
  return { user, preferences, permissions };
});
```

### ❌ Don't: Block the Middleware Pipeline with Slow Operations

```typescript
// BAD: 500ms delay on every message
builder.addMiddleware(async (ctx, next) => {
  await heavySyncOperation();
  await next();
});

// GOOD: Fire-and-forget or queue
builder.addMiddleware(async (ctx, next) => {
  // Don't await non-critical operations
  analytics.track('message.received', { ... });
  await next();
});
```

***

## Testing

### ✅ Do: Test Commands in Isolation

```typescript
import { Bot } from '@igniter-js/bot';

test('start command returns welcome message', async () => {
  const ctx = createMockContext({
    provider: 'telegram',
    author: { id: 'user_1', name: 'Test', username: 'test' },
  });
  let replyText = '';
  ctx.reply = async (text) => { replyText = text; };

  await startCommand.handle(ctx, {});
  expect(replyText).toContain('Welcome');
});
```

### ✅ Do: Use Memory Store in Tests

```typescript
const bot = IgniterBot.create()
  .withSessionStore(memoryStore())
  .addAdapter('telegram', mockTelegramAdapter)
  .build();
```

***

## Production Checklist

* [ ] **Environment variables** for all tokens and secrets
* [ ] **Global error handler** via `onError()`
* [ ] **Rate limiting** configured for your expected traffic
* [ ] **Persistent session store** (Redis, Prisma) — not memory
* [ ] **Webhook signature verification** enabled (Discord)
* [ ] **Logging middleware** with `includeContent: false` (privacy)
* [ ] **Bot initialized at module level** (not per-request)
* [ ] **Commands extracted** into separate files for maintainability
* [ ] **Business logic isolated** from command handlers
* [ ] **Webhook URLs configured** in platform dashboards

***

## Next Steps

<Cards>
  <Card title="Troubleshooting" description="Solve common errors, debug issues, and fix rate limit problems." href="/docs/bots/troubleshooting" />

  <Card title="Real-World Examples" description="Complete production bot scenarios with code." href="/docs/bots/real-world" />

  <Card title="API Reference" description="Complete API documentation for all methods and types." href="/docs/bots/api-reference" />
</Cards>


---

# Commands

> Master the command system — aliases, subcommands, Zod argument validation, command groups, and auto-registration across platforms.
URL: https://igniterjs.com/docs/bots/commands

## Commands

Commands are the primary way users interact with your bot. The framework provides a full-featured command system with aliases, subcommands, Zod validation, command groups, and automatic platform registration.

***

## Basic Command

Every command requires: `name`, `aliases`, `description`, `help`, and a `handle` function:

```typescript
builder.addCommand('start', {
  name: 'start',
  aliases: ['hello', 'hi'],
  description: 'Greets the user',
  help: 'Use /start to receive a welcome message',
  async handle(ctx) {
    await ctx.reply(`👋 Welcome, ${ctx.message.author.name}!`);
  },
});
```

| Field         | Type                           | Required | Description                                                 |
| ------------- | ------------------------------ | -------- | ----------------------------------------------------------- |
| `name`        | `string`                       | ✅        | Command name without slash. Must not contain `/` or spaces. |
| `aliases`     | `string[]`                     | ✅        | Alternative names. Each must follow the same rules.         |
| `description` | `string`                       | ✅        | Short description (used for platform registration).         |
| `help`        | `string`                       | ✅        | Detailed help shown on invalid usage.                       |
| `args`        | `ZodType`                      | ❌        | Zod schema for validating and typing arguments.             |
| `handle`      | `(ctx, args) => Promise<void>` | ✅        | The handler function.                                       |
| `subcommands` | `Record<string, BotCommand>`   | ❌        | Nested subcommands.                                         |

<Callout type="warn">
  Commands are validated at registration time using `Bot.command()`. Names with slashes, spaces, or missing required fields throw immediately.
</Callout>

***

## Aliases

Aliases let users trigger the same command with different names. All aliases are converted to lowercase and indexed for O(1) lookup:

```typescript
builder.addCommand('help', {
  name: 'help',
  aliases: ['commands', '?', 'h'], // /help, /commands, /?, /h all work
  description: 'Show available commands',
  help: 'Use /help to see available commands',
  async handle(ctx) { /* ... */ },
});
```

***

## Argument Validation (Zod)

Use the `args` field to validate and type command arguments:

```typescript
import { z } from 'zod';

builder.addCommand('search', {
  name: 'search',
  aliases: ['find', 's'],
  description: 'Search the catalog',
  help: 'Use /search &lt;query&gt; [category] to find items',
  args: z.object({
    query: z.string().min(2).describe('Search query (min 2 chars)'),
    category: z.enum(['books', 'movies', 'music']).optional(),
  }),
  async handle(ctx, args) {
    // args is fully typed: { query: string; category?: 'books' | 'movies' | 'music' }
    const results = await searchCatalog(args.query, args.category);

    if (results.length === 0) {
      await ctx.reply(`No results found for "${args.query}".`);
      return;
    }

    await ctx.reply(
      `🔍 Found **${results.length}** result(s) for "${args.query}":\n\n` +
      results.map((r, i) => `${i + 1}. ${r.title}`).join('\n'),
    );
  },
});
```

When a user provides invalid arguments, the framework returns a helpful error message automatically:

```
/invalid usage: search &lt;query&gt; [category]

Use /search &lt;query&gt; [category] to find items
```

<Callout type="info">
  The `args` schema uses `z.object()`. Nested objects, arrays, unions, and refinements are all supported — anything Zod can validate works here.
</Callout>

***

## Subcommands

Subcommands create nested command hierarchies. Define them inline or reference externally defined commands:

```typescript
builder.addCommand('admin', {
  name: 'admin',
  aliases: ['adm'],
  description: 'Admin commands',
  help: 'Use /admin &lt;subcommand&gt; for admin operations',
  subcommands: {
    ban: {
      name: 'ban',
      aliases: ['block'],
      description: 'Ban a user',
      help: 'Use /admin ban &lt;user_id&gt;',
      args: z.object({ userId: z.string() }),
      async handle(ctx, args) {
        await banUser(args.userId);
        await ctx.reply(`🚫 User ${args.userId} has been banned.`);
      },
    },
    kick: {
      name: 'kick',
      aliases: ['remove'],
      description: 'Kick a user',
      help: 'Use /admin kick &lt;user_id&gt;',
      args: z.object({ userId: z.string() }),
      async handle(ctx, args) {
        await kickUser(args.userId);
        await ctx.reply(`👢 User ${args.userId} has been kicked.`);
      },
    },
    stats: {
      name: 'stats',
      aliases: ['info'],
      description: 'Show admin stats',
      help: 'Use /admin stats',
      async handle(ctx) {
        const stats = await getAdminStats();
        await ctx.reply(`📊 **Admin Stats**\n\n${JSON.stringify(stats, null, 2)}`);
      },
    },
  },
  // The parent command itself has a handler for bare /admin
  async handle(ctx) {
    await ctx.reply(
      '🔧 **Admin Commands:**\n\n' +
      '/admin ban &lt;user_id&gt; — Ban a user\n' +
      '/admin kick &lt;user_id&gt; — Kick a user\n' +
      '/admin stats — Show statistics',
    );
  },
});
```

<Callout type="info">
  Subcommands don't need their own `name` or `aliases` — those are inherited from the parent command context.
</Callout>

***

## Command Groups

Group related commands with a common prefix using `.addCommandGroup()`:

```typescript
builder.addCommandGroup('admin', {
  ban: {
    name: 'ban',
    aliases: ['block'],
    description: 'Ban a user',
    help: 'Use /admin_ban &lt;user_id&gt;',
    async handle(ctx) { /* ... */ },
  },
  kick: {
    name: 'kick',
    aliases: ['remove'],
    description: 'Kick a user',
    help: 'Use /admin_kick &lt;user_id&gt;',
    async handle(ctx) { /* ... */ },
  },
  stats: {
    name: 'stats',
    aliases: [],
    description: 'Admin statistics',
    help: 'Use /admin_stats for statistics',
    async handle(ctx) { /* ... */ },
  },
});

// Results in commands: /admin_ban, /admin_kick, /admin_stats
```

Unlike subcommands, command groups create **flat, prefixed commands**. This is useful when platforms don't support nested command structures natively.

***

## Multiple Command Registration

Register several commands at once:

```typescript
builder.addCommands({
  start: { name: 'start', aliases: ['hello'], /* ... */ },
  help: { name: 'help', aliases: ['?'], /* ... */ },
  about: { name: 'about', aliases: ['info'], /* ... */ },
  contact: { name: 'contact', aliases: ['support'], /* ... */ },
});
```

***

## Dynamic Registration at Runtime

Commands can be added after the bot is built:

```typescript
const bot = builder.build();

// Later, dynamically register a new command
bot.registerCommand('maintenance', {
  name: 'maintenance',
  aliases: ['maint'],
  description: 'Toggle maintenance mode',
  help: 'Use /maintenance on|off',
  async handle(ctx) {
    const isMaintenance = await toggleMaintenance();
    await ctx.reply(`Maintenance mode: ${isMaintenance ? 'ON' : 'OFF'}`);
  },
});
```

This is useful for plugin systems, hot-reload during development, or commands that depend on runtime state.

***

## Platform Auto-Registration

Commands are automatically registered with platforms that support it:

* **Telegram** — Commands are set via `setMyCommands` API during `init()`
* **Discord** — Slash commands are registered via the Applications API during `init()`
* **WhatsApp** — Commands are handled entirely by the framework (no native command system)

<Callout type="warn">
  Discord slash commands may take up to 1 hour to propagate globally after registration. For development, register them to a specific guild for instant updates.
</Callout>

***

## Creating Commands in Separate Files

Use `Bot.command()` to create commands in separate files with validation:

```typescript
// commands/start.ts
import { Bot } from '@igniter-js/bot';

export const startCommand = Bot.command({
  name: 'start',
  aliases: ['hello', 'hi'],
  description: 'Greets the user',
  help: 'Use /start to receive a welcome message',
  async handle(ctx) {
    await ctx.reply('👋 Welcome!');
  },
});

// lib/bot.ts
import { startCommand } from './commands/start';

const bot = IgniterBot.create()
  .addCommand('start', startCommand)
  .build();
```

`Bot.command()` validates the command structure at creation time, catching errors early.

***

## Best Practices

* ✅ **Use descriptive names** — `search` is better than `s`. Aliases handle shortcuts.
* ✅ **Always provide help text** — Users will invoke `/command --help` style usage.
* ✅ **Validate with Zod** — Even simple commands benefit from typed arguments.
* ✅ **Organize related commands with groups** — Keeps your bot configuration readable.
* ✅ **Keep handlers focused** — Extract business logic into separate functions for testability.
* ❌ **Don't create too many top-level commands** — Use subcommands or groups for organization.
* ❌ **Don't hardcode platform-specific logic** — Use `ctx.provider` to check the current platform only when truly needed.

***

## Next Steps

<Cards>
  <Card title="Adapters" description="Configure Telegram, WhatsApp, and Discord platform adapters." href="/docs/bots/adapters" />

  <Card title="Middlewares" description="Add auth, rate-limiting, and logging to your bot." href="/docs/bots/middlewares" />

  <Card title="Sessions" description="Persist conversational state across messages." href="/docs/bots/sessions" />
</Cards>


---

# Core Concepts

> Master the builder pattern, adapters, commands, context, middlewares, and plugins that power @igniter-js/bot.
URL: https://igniterjs.com/docs/bots/core-concepts

## Core Concepts

This page explains the architectural pillars of `@igniter-js/bot`. Understanding these concepts lets you build complex, production-grade bots with confidence.

***

## The Builder Pattern

The `IgniterBot` builder is the **only recommended way** to construct bots. It provides a fluent, type-safe API where each method narrows the generic type parameters, giving you precise autocomplete at every step.

### Builder Lifecycle

```
IgniterBot.create()
  → .withHandle()        // Set bot identity
  → .withSessionStore()  // Configure session storage
  → .withLogger()        // Structured logging
  → .withOptions()       // Timeouts, retries, etc.
  → .addAdapters()       // Platform adapters (Telegram, WhatsApp, Discord)
  → .addCommands()       // Register commands
  → .addMiddlewares()    // Middleware pipeline
  → .usePlugin()         // Load plugins
  → .onMessage()         // Event listeners
  → .onError()           // Error handling
  → .onStart()           // Startup hooks
  → .onCommand()         // Command execution hooks
  → .build()             // Materialize into immutable Bot instance
```

After `.build()`, the `Bot` instance is **immutable**. All configuration happens through the builder. The bot instance can still dynamically register commands, adapters, and middlewares at runtime using `registerCommand()`, `registerAdapter()`, and `use()`.

### Identity: Handle, ID, and Name

The `withHandle()` method is the primary identity setter. If you don't explicitly set `id` and `name`, they're derived automatically:

```typescript
IgniterBot.create()
  .withHandle('@ecommerce_bot')
  // → id: 'ecommerce_bot'
  // → name: 'Ecommerce Bot'
  .build();
```

You can override them explicitly:

```typescript
IgniterBot.create()
  .withHandle('@ecommerce_bot')
  .withId('prod-ecommerce-v2')
  .withName('E-Commerce Assistant')
  .build();
```

<Callout type="info">
  The handle is used for **mention detection** in group chats. If a global handle is set, all adapters use it. Each adapter can also override the handle in its config.
</Callout>

### Type-Safe Generics

The builder tracks your configuration in its generic parameters:

```typescript
const b1 = IgniterBot.create()
  .addAdapter('telegram', tgAdapter)
// b1: IgniterBotBuilder<{ telegram: TelegramAdapter }, {}, BotContext>

const b2 = b1.addCommand('start', startCmd)
// b2: IgniterBotBuilder<{ telegram: ... }, { start: BotCommand }, BotContext>

const b3 = b2.addMiddleware(authMiddleware)
// b3: IgniterBotBuilder<{ telegram: ... }, { start: ... }, BotContext & AuthContextAdditions>
```

This means TypeScript knows exactly which adapters and commands are available throughout the entire builder chain.

***

## Adapters

Adapters are the bridge between the bot framework and platform-specific APIs. Each adapter:

1. **Parses** incoming requests into a normalized `BotContext`
2. **Declares** its capabilities (supported content types, actions, features, limits)
3. **Provides** send methods for each supported content type
4. **Initializes** by registering webhooks, commands, etc.
5. **Verifies** webhook signatures when applicable

### How Adapters Work

```
HTTP Request → Adapter.verify() (optional signature check)
             → Adapter.handle() → BotContext
             → Bot engine (middlewares, command routing, event listeners)
             → Handler calls ctx.reply() / ctx.sendTyping() / etc.
             → Adapter.sendText() / sendImage() / etc.
             → Platform API
```

### Declared Capabilities

Every adapter declares its capabilities so the framework can validate operations at runtime:

```typescript
const capabilities = {
  content: {
    text: true,        // Can send plain text
    image: true,       // Can send images
    video: true,       // Can send video
    audio: true,       // Can send audio
    document: true,    // Can send files
    sticker: true,     // Can send stickers
    location: true,    // Can share location
    contact: true,     // Can share contacts
    poll: true,        // Can create polls
    interactive: true, // Can send buttons/keyboards
  },
  actions: {
    edit: true,        // Can edit messages
    delete: true,      // Can delete messages
    react: false,      // Can add reactions
    pin: true,         // Can pin messages
    thread: false,     // Has thread support
  },
  features: {
    webhooks: true,    // Supports webhooks
    longPolling: true, // Supports long polling
    commands: true,    // Has native command support
    mentions: true,    // Supports @mentions
    groups: true,      // Supports group chats
    channels: true,    // Supports channels
    users: true,       // Has user management
    files: true,       // Supports file handling
  },
  limits: {
    maxMessageLength: 4096,
    maxFileSize: 50 * 1024 * 1024, // 50MB
    maxButtonsPerMessage: 8,
  },
}
```

If you try to send a poll on WhatsApp (which doesn't support polls), the framework throws a `BotError` with code `CONTENT_TYPE_NOT_SUPPORTED`.

***

## BotContext

The `BotContext` is the normalized representation of every incoming interaction. It's passed to every middleware, command handler, and event listener.

```typescript
interface BotContext {
  // Event type: 'start' | 'message' | 'error'
  event: BotEvent

  // Platform identifier: 'telegram' | 'whatsapp' | 'discord'
  provider: string

  // Bot instance and send capability
  bot: {
    id: string
    name: string
    send: (params) => Promise<void>
    getAdapter?: (provider: string) => IBotAdapter | undefined
    getAdapters?: () => Record<string, IBotAdapter>
  }

  // Channel / chat information
  channel: {
    id: string
    name: string
    isGroup: boolean
  }

  // Message details
  message: {
    id?: string
    content?: BotContent
    attachments?: BotAttachmentContent[]
    author: {
      id: string
      name: string
      username: string
    }
    isMentioned: boolean
  }

  // Session helper for conversational state
  session: BotSessionHelper

  // Convenience reply methods
  reply(content: string | BotOutboundContent, options?: BotSendOptions): Promise<void>
  replyWithButtons(text: string, buttons: BotButton[], options?: BotSendOptions): Promise<void>
  replyWithImage(image: string | File, caption?: string, options?: BotSendOptions): Promise<void>
  replyWithDocument(file: File, caption?: string, options?: BotSendOptions): Promise<void>
  editMessage?(messageId: string, content: BotOutboundContent): Promise<void>
  deleteMessage?(messageId: string): Promise<void>
  react?(emoji: string, messageId?: string): Promise<void>
  sendTyping?(): Promise<void>
}
```

<Callout type="info">
  Methods like `editMessage`, `deleteMessage`, `react`, and `sendTyping` are optional — they're only available when the current adapter supports those actions.
</Callout>

***

## The Middleware Pipeline

Middlewares execute in order for every incoming message. Each middleware receives the context and a `next()` function. Calling `next()` passes control to the next middleware. **Not** calling `next()` stops the pipeline.

```mermaid
graph LR
    A[Incoming Message] --> M1[Auth Middleware]
    M1 --> M2[Rate Limit Middleware]
    M2 --> M3[Logging Middleware]
    M3 --> M4[Custom Middleware]
    M4 --> H[Command Handler / Event Listener]
```

### Middleware Signature

```typescript
type Middleware<TContextIn, TContextOut> = (
  ctx: TContextIn,
  next: () => Promise<void>,
) => Promise<void | Partial<TContextOut>>
```

A middleware can:

1. **Enrich the context** by returning an object — merged into the context for downstream handlers
2. **Block the request** by not calling `next()`
3. **Perform side effects** before and after `next()`
4. **Handle errors** with try/catch around `next()`

```typescript
// Context enrichment
builder.addMiddleware(async (ctx, next) => {
  const user = await db.users.findById(ctx.message.author.id);
  await next();
  return { user }; // available in downstream context
});

// Request blocking
builder.addMiddleware(async (ctx, next) => {
  if (ctx.message.author.id === 'blocked_user') {
    await ctx.reply('You are blocked.');
    return; // No next() → pipeline stops
  }
  await next();
});

// Timing middleware
builder.addMiddleware(async (ctx, next) => {
  const start = Date.now();
  await next();
  console.log(`Request took ${Date.now() - start}ms`);
});
```

***

## Plugins

Plugins package commands, middlewares, adapters, and lifecycle hooks into reusable, shareable modules.

```typescript
interface BotPlugin {
  name: string
  version: string
  description?: string
  commands?: Record<string, BotCommand>
  middlewares?: Middleware[]
  adapters?: Record<string, IBotAdapter>
  hooks?: {
    onStart?: () => Promise<void> | void
    onMessage?: (ctx: BotContext) => Promise<void> | void
    onError?: (ctx: BotContext & { error: BotError }) => Promise<void> | void
    onStop?: () => Promise<void> | void
  }
  config?: Record<string, any>
}
```

When a plugin is loaded via `.usePlugin()`, the builder automatically merges its commands, middlewares, adapters, and hooks into the bot configuration. This means you can build a plugin once and reuse it across multiple bots.

***

## Sessions

Sessions persist conversational state across messages. The framework provides:

* A `BotSessionStore` interface for pluggable storage backends
* A built-in `MemorySessionStore` for development
* A `BotSessionHelper` attached to `ctx.session` for easy access in handlers

```typescript
// Session shape
interface BotSession {
  userId: string
  channelId: string
  data: Record<string, any>      // Your application state
  createdAt: Date
  updatedAt: Date
  expiresAt?: Date                // Auto-cleanup on expiration
}

// Helper methods on ctx.session
interface BotSessionHelper extends BotSession {
  save(): Promise<void>                                    // Persist changes
  delete(): Promise<void>                                  // Remove session
  update(data: Partial<Record<string, any>>): Promise<void> // Merge data
}
```

***

## Event System

The bot emits events that you can listen to:

| Event     | Trigger                         | Context Fields                   |
| --------- | ------------------------------- | -------------------------------- |
| `message` | Every incoming message          | Full `BotContext`                |
| `start`   | Bot initialization (`.start()`) | No message data                  |
| `error`   | Any handler throws              | `BotContext` + `error: BotError` |

```typescript
// Via builder
builder.onMessage(async (ctx) => { /* ... */ })
builder.onError(async (ctx) => { /* ctx.error */ })
builder.onStart(async () => { /* ... */ })

// Via Bot instance
bot.on('message', async (ctx) => { /* ... */ })
bot.on('error', async (ctx) => { /* ... */ })
```

***

## Error Handling

The framework uses a custom `BotError` class with error codes:

```typescript
const BotErrorCodes = {
  CLIENT_NOT_PROVIDED: 'CLIENT_NOT_PROVIDED',
  PROVIDER_NOT_FOUND: 'PROVIDER_NOT_FOUND',
  COMMAND_NOT_FOUND: 'COMMAND_NOT_FOUND',
  INVALID_COMMAND_PARAMETERS: 'INVALID_COMMAND_PARAMETERS',
  ADAPTER_HANDLE_RETURNED_NULL: 'ADAPTER_HANDLE_RETURNED_NULL',
  CONTENT_TYPE_NOT_SUPPORTED: 'CONTENT_TYPE_NOT_SUPPORTED',
  INVALID_CONTENT: 'INVALID_CONTENT',
}

class BotError extends Error {
  code: BotErrorCode
  meta?: Record<string, unknown>
}
```

Errors can be caught in middleware, event listeners, or the global error handler:

```typescript
builder.onError(async (ctx) => {
  const botError = ctx.error as BotError;
  console.error(`[${botError.code}] ${botError.message}`, botError.meta);
  await ctx.reply('Something went wrong. Our team has been notified.');
});
```

***

## Next Steps

<Cards>
  <Card title="Commands" description="Master aliases, subcommands, and Zod validation." href="/docs/bots/commands" />

  <Card title="Adapters" description="Deep dive into Telegram, WhatsApp, and Discord adapters." href="/docs/bots/adapters" />

  <Card title="Middlewares" description="Auth, rate-limiting, logging, and custom middleware patterns." href="/docs/bots/middlewares" />
</Cards>


---

# Framework Integration

> Integrate @igniter-js/bot with Next.js, TanStack Start, Express, Fastify, Hono, and any Node.js web framework. Handle webhooks with minimal boilerplate.
URL: https://igniterjs.com/docs/bots/framework-integration

## Framework Integration

`@igniter-js/bot` is framework-agnostic at its core — adapters work with the standard `Request`/`Response` API. This page covers integration patterns for popular frameworks.

***

## Next.js App Router

The `nextRouteHandlerAdapter` provides a ready-to-use route handler.

### Route Setup

```typescript
// app/api/bot/[adapter]/[botId]/route.ts
import { nextRouteHandlerAdapter } from '@igniter-js/bot';
import { bot } from '@/lib/bot';

export const { GET, POST } = nextRouteHandlerAdapter({
  assistant_bot: bot,
});
```

**Dynamic segments:**

* `[adapter]` — Platform: `telegram`, `whatsapp`, `discord`
* `[botId]` — Bot ID (derived from handle: `assistant_bot`)

### Webhook URL

Set your webhook URL to:

```
https://your-domain.com/api/bot/telegram/assistant_bot
```

The `GET` handler handles webhook verification (Telegram setup, Discord signature checks). The `POST` handler processes incoming messages.

### Multiple Bots

```typescript
import { nextRouteHandlerAdapter } from '@igniter-js/bot';
import { supportBot, salesBot, internalBot } from '@/lib/bots';

export const { GET, POST } = nextRouteHandlerAdapter({
  support_bot: supportBot,
  sales_bot: salesBot,
  internal_bot: internalBot,
});
```

### Local Development

Use a tunneling service to expose your local server:

```bash
# ngrok
ngrok http 3000

# localtunnel
npx localtunnel --port 3000 --subdomain my-bot-dev
```

Then set your Telegram webhook to: `https://my-bot-dev.loca.lt/api/bot/telegram/assistant_bot`

***

## TanStack Start

The `tanstackStartRouteHandlerAdapter` follows the same pattern:

```typescript
// app/routes/api/bot/$adapter/$botId.ts
import { tanstackStartRouteHandlerAdapter } from '@igniter-js/bot';
import { bot } from '@/lib/bot';

export const { GET, POST } = tanstackStartRouteHandlerAdapter({
  assistant_bot: bot,
});
```

***

## Express

Bot works with Express through the standard `Request`/`Response` pattern:

```typescript
import express from 'express';
import { bot } from './lib/bot';

const app = express();

// Convert Express req to Web Request
function toWebRequest(req: express.Request): Request {
  const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
  return new Request(url, {
    method: req.method,
    headers: new Headers(req.headers as Record<string, string>),
    body: req.method === 'POST' ? JSON.stringify(req.body) : undefined,
  });
}

// Bot webhook handler
app.all('/api/bot/:adapter', async (req, res) => {
  try {
    const webRequest = toWebRequest(req);
    const webResponse = await bot.handle(req.params.adapter, webRequest);

    // Forward status and headers
    res.status(webResponse.status);
    webResponse.headers.forEach((value, key) => {
      res.setHeader(key, value);
    });

    // Forward body
    const body = await webResponse.text();
    res.send(body);
  } catch (error) {
    console.error('Bot handler error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.listen(3000, () => {
  console.log('Bot server running on http://localhost:3000');
});
```

### Express with Multiple Bots

```typescript
import { supportBot, salesBot } from './lib/bots';

const bots = { support: supportBot, sales: salesBot };

app.all('/api/bot/:botId/:adapter', async (req, res) => {
  const bot = bots[req.params.botId];
  if (!bot) {
    return res.status(404).json({ error: 'Bot not found' });
  }

  const webRequest = toWebRequest(req);
  const webResponse = await bot.handle(req.params.adapter, webRequest);

  res.status(webResponse.status);
  webResponse.headers.forEach((value, key) => res.setHeader(key, value));
  const body = await webResponse.text();
  res.send(body);
});
```

***

## Fastify

```typescript
import Fastify from 'fastify';
import { bot } from './lib/bot';

const fastify = Fastify({ logger: true });

// Bot webhook handler
fastify.all('/api/bot/:adapter', async (request, reply) => {
  const url = `${request.protocol}://${request.hostname}${request.url}`;
  const webRequest = new Request(url, {
    method: request.method,
    headers: request.headers as HeadersInit,
    body: request.method === 'POST' ? JSON.stringify(request.body) : undefined,
  });

  const webResponse = await bot.handle(
    (request.params as any).adapter,
    webRequest,
  );

  reply.status(webResponse.status);

  webResponse.headers.forEach((value, key) => {
    reply.header(key, value);
  });

  const body = await webResponse.text();
  reply.send(body);
});

await fastify.listen({ port: 3000 });
```

***

## Hono

Hono's native `Request`/`Response` API makes integration trivial:

```typescript
import { Hono } from 'hono';
import { bot } from './lib/bot';

const app = new Hono();

app.all('/api/bot/:adapter', async (c) => {
  const webResponse = await bot.handle(c.req.param('adapter'), c.req.raw);
  return webResponse;
});

export default app;
```

***

## Bun.serve / Node.js HTTP

For minimal Node.js or Bun servers:

```typescript
// Bun
import { bot } from './lib/bot';

Bun.serve({
  port: 3000,
  async fetch(request) {
    const url = new URL(request.url);
    const adapter = url.pathname.split('/')[3]; // /api/bot/{adapter}
    if (!adapter) return new Response('Not Found', { status: 404 });

    return bot.handle(adapter, request);
  },
});
```

```typescript
// Node.js http module
import { createServer } from 'http';
import { bot } from './lib/bot';

const server = createServer(async (req, res) => {
  const url = new URL(req.url!, `http://${req.headers.host}`);
  const adapter = url.pathname.split('/')[3];

  if (!adapter) {
    res.writeHead(404);
    res.end('Not Found');
    return;
  }

  const webRequest = new Request(url.toString(), {
    method: req.method,
    headers: req.headers as HeadersInit,
    body: req.method === 'POST' ? await readBody(req) : undefined,
  });

  const webResponse = await bot.handle(adapter, webRequest);

  res.writeHead(webResponse.status, Object.fromEntries(webResponse.headers));
  const body = await webResponse.text();
  res.end(body);
});

server.listen(3000);

function readBody(req: IncomingMessage): Promise<string> {
  return new Promise((resolve) => {
    let body = '';
    req.on('data', (chunk) => (body += chunk));
    req.on('end', () => resolve(body));
  });
}
```

***

## Proactive Messaging (Push Notifications)

To send messages proactively (not in response to a user message), use `bot.send()`:

```typescript
// Send a notification to a user on WhatsApp
await bot.send({
  provider: 'whatsapp',
  channel: '5511999999999', // User's phone number
  content: {
    type: 'interactive',
    text: '📦 Your order #12345 has shipped!',
    buttons: [
      { id: 'track', label: '📍 Track Order', action: 'callback', data: 'track_12345' },
      { id: 'support', label: '🆘 Support', action: 'callback', data: 'support_12345' },
    ],
  },
});

// Send to Telegram
await bot.send({
  provider: 'telegram',
  channel: '123456789', // Telegram chat ID
  content: { type: 'text', content: '🔔 Reminder: Your appointment is tomorrow at 2 PM.' },
});

// Send an image on Discord
await bot.send({
  provider: 'discord',
  channel: '789012345', // Discord channel ID
  content: {
    type: 'image',
    content: 'https://cdn.example.com/chart.png',
    caption: '📊 Weekly Analytics Report',
  },
});
```

<Callout type="info">
  For proactive messaging, you need to store the user's platform-specific channel ID (Telegram `chat_id`, WhatsApp phone number, Discord `channel_id`). This is available in `ctx.channel.id` during normal interactions.
</Callout>

***

## Serverless / Edge

For serverless environments (Vercel, Cloudflare Workers, AWS Lambda):

### Vercel Edge Functions

```typescript
// app/api/bot/[adapter]/route.ts
import { bot } from '@/lib/bot';

export async function GET(request: Request, { params }: { params: { adapter: string } }) {
  return bot.handle(params.adapter, request);
}

export async function POST(request: Request, { params }: { params: { adapter: string } }) {
  return bot.handle(params.adapter, request);
}
```

### Cloudflare Workers

```typescript
import { bot } from './lib/bot';

export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const adapter = url.pathname.split('/')[3];

    if (!adapter) {
      return new Response('Not Found', { status: 404 });
    }

    return bot.handle(adapter, request);
  },
};
```

<Callout type="warn">
  Serverless environments have cold starts. Initialize your bot **outside** the handler function (at module level) to reuse the instance across invocations.
</Callout>

***

## Environment Variables in Production

In production, configure your webhook URLs through the platform dashboards:

| Platform | Where to Set                                             |
| -------- | -------------------------------------------------------- |
| Telegram | `setWebhook` API (called automatically by `bot.start()`) |
| WhatsApp | Meta Developer Dashboard → Webhook Configuration         |
| Discord  | Discord Developer Portal → Interactions Endpoint URL     |

***

## Next Steps

<Cards>
  <Card title="Real-World Examples" description="Complete production bot scenarios with code." href="/docs/bots/real-world" />

  <Card title="API Reference" description="Complete API documentation for all methods and types." href="/docs/bots/api-reference" />

  <Card title="Best Practices" description="Security, performance, and architecture patterns." href="/docs/bots/best-practices" />
</Cards>


---

# Introduction

> Universal bot framework for Node.js. Build bots once, deploy to Telegram, WhatsApp, Discord, and more — with a fluent builder API, middleware pipeline, session management, and plugin system.
URL: https://igniterjs.com/docs/bots

## Overview

`@igniter-js/bot` is a **multi-platform bot framework** for Node.js and Bun. It lets you build conversational bots that run on Telegram, WhatsApp, and Discord simultaneously — sharing commands, middlewares, and session state across all platforms.

You define your bot once using the **builder pattern**, add adapters for each platform, and get a unified API for handling messages, commands, and interactive content — with full TypeScript autocomplete everywhere.

<Callout type="info">
  Bot works with **any platform that can receive HTTP requests**. The adapter pattern means you can write a custom adapter for any chat platform in under 100 lines, and it automatically works with the entire middleware, plugin, and session system.
</Callout>

### Key Features

* **Multi-Platform** — Telegram, WhatsApp, Discord, and custom adapters. One codebase, every chat platform.
* **Fluent Builder API** — `IgniterBot.create().withHandle().addAdapters().addCommand().build()` — fully typed at every step.
* **Command System** — Slash commands with aliases, subcommands, Zod argument validation, and automatic platform registration.
* **Middleware Pipeline** — `auth`, `rateLimit`, `logging` built-in. Extend with custom middleware for any use case.
* **Plugin Architecture** — Package commands, middlewares, adapters, and hooks into reusable plugins.
* **Session Management** — Persistent conversational state with pluggable storage (memory, Redis, Prisma).
* **Rich Content Types** — Send text, images, video, audio, documents, stickers, location, contacts, polls, and interactive buttons.
* **Type-Safe Context** — `BotContext` gives you typed access to message, channel, author, session, and reply helpers.
* **Framework Integration** — Native handlers for Next.js App Router and TanStack Start. Express/Fastify compatible via standard `Request`/`Response`.
* **Adapter Client** — Every adapter exposes a pre-configured HTTP client for making direct API calls when needed.

***

## Architecture

Bot follows the **adapter pattern** — the same pattern used across the Igniter.js ecosystem. The core handles commands, middlewares, sessions, and event routing. Adapters translate between platform-specific APIs and the normalized `BotContext`.

```mermaid
graph TD
    A[Incoming Request] --> B[Platform Adapter]
    B --> C[Adapter.handle]
    C --> D{Normalized BotContext}
    D --> E[Session Loader]
    E --> F[Pre-Process Hooks]
    F --> G[Middleware Pipeline]
    G --> H[Command Router]
    H --> I[Command Handler]
    G --> J[Event Listeners]
    I --> K[Reply via Adapter]
    J --> K
    K --> L[Platform API]
```

Every incoming message flows through: **adapter parsing → session loading → pre-process hooks → middleware chain → command routing → handler execution → reply dispatch**.

***

## Quick Start

Get a cross-platform bot running in under three minutes.

<Steps>
  <Step>
    ### Install

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        npm install @igniter-js/bot zod
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @igniter-js/bot zod
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @igniter-js/bot zod
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @igniter-js/bot zod
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Create Your Bot

    ```typescript
    import { IgniterBot, telegram, whatsapp, discord, memoryStore } from '@igniter-js/bot';

    const bot = IgniterBot
      .create()
      .withHandle('@my_awesome_bot')
      .withSessionStore(memoryStore())
      .addAdapters({
        telegram: telegram({ token: process.env.TELEGRAM_TOKEN! }),
        whatsapp: whatsapp({
          token: process.env.WHATSAPP_TOKEN!,
          phone: process.env.WHATSAPP_PHONE!,
        }),
        discord: discord({
          token: process.env.DISCORD_TOKEN!,
          applicationId: process.env.DISCORD_APP_ID!,
          publicKey: process.env.DISCORD_PUBLIC_KEY!,
        }),
      })
      .addCommand('start', {
        name: 'start',
        aliases: ['hello', 'hi'],
        description: 'Greets the user',
        help: 'Use /start to receive a welcome message',
        async handle(ctx) {
          await ctx.reply(
            `👋 Hello, ${ctx.message.author.name}! I'm running on ${ctx.provider}.`,
          );
        },
      })
      .addCommand('ping', {
        name: 'ping',
        aliases: [],
        description: 'Check bot responsiveness',
        help: 'Use /ping to check if the bot is alive',
        async handle(ctx) {
          const start = Date.now();
          await ctx.reply('Pong! 🏓');
        },
      })
      .build();

    await bot.start();
    ```

    ✅ **The bot is now running and ready to accept requests.**
  </Step>

  <Step>
    ### Wire Up a Route (Next.js)

    ```typescript
    // app/api/bot/[adapter]/route.ts
    import { nextRouteHandlerAdapter } from '@igniter-js/bot';
    import { bot } from '@/lib/bot';

    export const { GET, POST } = nextRouteHandlerAdapter({
      'my_awesome_bot': bot,
    });
    ```

    Now your bot responds to Telegram webhooks, WhatsApp Cloud API, and Discord interactions — all through a single route.
  </Step>
</Steps>

***

## Core Concepts

<Accordions>
  <Accordion title="Builder Pattern">
    The `IgniterBot` builder is the recommended way to construct bots. It provides a fluent, type-safe API where each method narrows the generic types:

    ```typescript
    const bot = IgniterBot
      .create()                    // Start building
      .withHandle('@bot')          // Set global handle
      .withSessionStore(store)     // Configure session storage
      .withLogger(pino())          // Structured logging
      .addAdapter('telegram', tg)  // Add a platform adapter
      .addCommand('start', cmd)    // Register a command
      .addMiddleware(authMw)       // Add middleware
      .usePlugin(analytics)        // Load a plugin
      .onMessage(messageHandler)   // Listen to events
      .onError(errorHandler)       // Handle errors
      .onStart(startupHook)        // Run on initialization
      .build()                     // Materialize the Bot instance
    ```

    After `.build()`, the bot is immutable. All configuration happens through the builder.
  </Accordion>

  <Accordion title="Adapters">
    Adapters translate between platform-specific APIs and the normalized `BotContext`. Each adapter declares its **capabilities** (supported content types, actions, features, and limits) so the framework can validate operations at runtime.

    **First-party adapters:**

    * **Telegram** — Full support: webhooks, long polling, commands, inline keyboards, all content types
    * **WhatsApp** — Cloud API: text, media, interactive buttons, contacts, location
    * **Discord** — Interactions API: slash commands, buttons, embeds, thread support

    Each adapter provides typed configuration via Zod schemas and supports environment variable defaults.
  </Accordion>

  <Accordion title="Commands">
    Commands are the primary interaction pattern. They support:

    * **Aliases** — `/start`, `/hello`, `/hi` all pointing to the same handler
    * **Subcommands** — Nested command structures (e.g., `/admin ban`, `/admin kick`)
    * **Zod Validation** — Type-safe argument parsing with automatic error messages
    * **Automatic Registration** — Commands are auto-registered with platforms that support it (Telegram bot commands, Discord slash commands)
    * **Command Groups** — Prefix commands logically: `builder.addCommandGroup('admin', { ... })`

    ```typescript
    builder.addCommand('search', {
      name: 'search',
      aliases: ['find', 's'],
      description: 'Search for items',
      help: 'Use /search &lt;query&gt; to find items',
      args: z.object({ query: z.string().min(2) }),
      async handle(ctx, args) {
        const results = await searchDatabase(args.query);
        await ctx.reply(`Found ${results.length} results.`);
      },
    })
    ```
  </Accordion>

  <Accordion title="Middlewares">
    Middlewares execute in sequence for every incoming message. They can enrich the context, block requests, or perform side effects:

    ```typescript
    // Custom middleware
    builder.addMiddleware(async (ctx, next) => {
      console.log(`[${ctx.provider}] ${ctx.message.author.name}: ${ctx.message.content}`);
      const start = Date.now();
      await next(); // Continue to the next middleware or handler
      console.log(`Completed in ${Date.now() - start}ms`);
    })
    ```

    **Built-in middlewares:**

    * `authMiddleware` — User/channel allowlists, blocklists, role-based access
    * `rateLimitMiddleware` — Configurable rate limiting with memory or Redis store
    * `loggingMiddleware` — Structured logging with presets (minimal, standard, verbose, production)
  </Accordion>

  <Accordion title="Plugins">
    Plugins package commands, middlewares, adapters, and lifecycle hooks into reusable modules:

    ```typescript
    // Built-in analytics plugin
    builder.usePlugin(analyticsPlugin({
      trackEvent: async (event, props) => {
        await posthog.capture(event, props);
      },
      trackMessages: true,
      trackCommands: true,
    }))
    ```

    Plugins can also register their own commands (e.g., `/stats` from the analytics plugin), middlewares, and adapters — all composed automatically into the bot.
  </Accordion>

  <Accordion title="Sessions">
    Sessions persist conversational state across messages. The framework provides a `BotSessionStore` interface with a built-in in-memory store and support for custom backends:

    ```typescript
    // In-memory (development)
    builder.withSessionStore(memoryStore())

    // Redis (production)
    builder.withSessionStore(redisStore(redisClient))
    ```

    Access sessions in handlers via `ctx.session`:

    ```typescript
    async handle(ctx) {
      await ctx.session.update({ step: 'awaiting_name' });
      const currentStep = ctx.session.data.step;
    }
    ```
  </Accordion>
</Accordions>

***

## Real-World Use Cases

Bot powers conversational applications across many domains:

| Use Case                  | Description                                                                   |
| ------------------------- | ----------------------------------------------------------------------------- |
| **Customer Support**      | Route inquiries across Telegram, WhatsApp, and Discord with a single codebase |
| **E-commerce Bots**       | Product search, order tracking, cart management with interactive buttons      |
| **Community Management**  | Moderation commands, welcome messages, polls, and announcements               |
| **SaaS Onboarding**       | Step-by-step guided setup flows with persistent session state                 |
| **Notification Services** | Push alerts to users on their preferred platform via proactive messaging      |
| **Internal Tools**        | DevOps bots for deployment status, incident alerts, and team coordination     |

***

## Next Steps

<Cards>
  <Card title="Installation" description="Install and configure @igniter-js/bot with the right adapters for your platforms." href="/docs/bots/installation" />

  <Card title="Quick Start" description="Build a production-ready bot in 3 minutes with step-by-step guidance." href="/docs/bots/quick-start" />

  <Card title="Core Concepts" description="Deep dive into the builder, adapters, commands, context, middlewares, and plugins." href="/docs/bots/core-concepts" />

  <Card title="Commands" description="Master the command system with aliases, subcommands, and Zod validation." href="/docs/bots/commands" />
</Cards>


---

# Installation

> Install and configure @igniter-js/bot for your runtime. Choose the right adapters and set up your first bot in minutes.
URL: https://igniterjs.com/docs/bots/installation

## Installation

`@igniter-js/bot` works on **Node.js 18+** and **Bun 1.0+**. It requires `zod` as a peer dependency for adapter parameter validation.

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/bot zod
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/bot zod
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/bot zod
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/bot zod
    ```
  </Tab>
</Tabs>

### Runtime Requirements

| Runtime      | Version | Notes                                           |
| ------------ | ------- | ----------------------------------------------- |
| Node.js      | 18+     | Full support for all adapters                   |
| Bun          | 1.0+    | Native `File` API support for media uploads     |
| Edge Runtime | Limited | Only adapters that don't use Node-specific APIs |

***

## Choosing Adapters

Bot comes with three first-party adapters. Install only the platforms you need — the package is tree-shakeable.

### Telegram

**Best for:** General-purpose bots, group management, channel automation

```typescript
import { telegram } from '@igniter-js/bot';

const tgAdapter = telegram({
  token: process.env.TELEGRAM_TOKEN!,
  handle: '@your_bot', // Optional: overrides global handle
  webhook: {
    url: 'https://your-domain.com/api/bot/telegram',
    secret: process.env.TELEGRAM_WEBHOOK_SECRET!, // Optional: validates webhook authenticity
    dropPendingUpdates: true, // Clear pending updates on restart (default: true)
  },
});
```

**Environment variables supported:**

* `TELEGRAM_TOKEN` — Bot API token (from @BotFather)
* `TELEGRAM_WEBHOOK_URL` — Public HTTPS endpoint for webhook
* `TELEGRAM_WEBHOOK_SECRET` — Secret token for webhook verification

### WhatsApp (Cloud API)

**Best for:** Customer support, e-commerce, notification bots

```typescript
import { whatsapp } from '@igniter-js/bot';

const waAdapter = whatsapp({
  token: process.env.WHATSAPP_TOKEN!,
  phone: process.env.WHATSAPP_PHONE!, // Phone number ID from Meta Business
});
```

<Callout type="warn">
  WhatsApp Cloud API requires a Meta Business account and a verified phone number. The `init` method is a no-op — webhook setup is managed through the Meta Developer dashboard.
</Callout>

### Discord

**Best for:** Community servers, gaming, developer communities

```typescript
import { discord } from '@igniter-js/bot';

const dcAdapter = discord({
  token: process.env.DISCORD_TOKEN!,
  applicationId: process.env.DISCORD_APP_ID!,
  publicKey: process.env.DISCORD_PUBLIC_KEY!, // Required for interaction verification
});
```

<Callout type="info">
  Discord requires interaction signature verification. Always provide `publicKey` in production, or the adapter will log a warning on every request.
</Callout>

### Adapter Capability Comparison

| Feature             | Telegram         | WhatsApp    | Discord       |
| ------------------- | ---------------- | ----------- | ------------- |
| Text messages       | ✅                | ✅           | ✅             |
| Images              | ✅                | ✅           | ✅             |
| Video               | ✅                | ✅           | ✅             |
| Audio               | ✅                | ✅           | ✅             |
| Documents           | ✅                | ✅           | ✅             |
| Stickers            | ✅                | ✅           | ❌             |
| Location            | ✅                | ✅           | ❌             |
| Contacts            | ✅                | ✅           | ❌             |
| Polls               | ✅                | ❌           | ❌             |
| Interactive buttons | ✅                | ✅ (max 3)   | ✅ (max 5/row) |
| Edit messages       | ✅                | ❌           | ✅             |
| Delete messages     | ✅                | ❌           | ✅             |
| Reactions           | ❌                | ✅           | ✅             |
| Threads             | ❌                | ❌           | ✅             |
| Webhooks            | ✅                | ✅           | ✅             |
| Long polling        | ✅                | ❌           | ❌             |
| Slash commands      | ❌ (bot commands) | ❌           | ✅             |
| Groups              | ✅                | ✅           | ✅ (servers)   |
| Max message length  | 4,096 chars      | 4,096 chars | 2,000 chars   |
| Max file size       | 50 MB            | 100 MB      | 25 MB         |

***

## Framework Integration Packages

### Next.js App Router

The `nextRouteHandlerAdapter` creates a ready-to-use route handler:

```typescript
// app/api/bot/[adapter]/[botId]/route.ts
import { nextRouteHandlerAdapter } from '@igniter-js/bot';

export const { GET, POST } = nextRouteHandlerAdapter(bots);
```

The adapter expects dynamic route segments `[adapter]` and `[botId]`. It automatically handles webhook verification (GET) and message processing (POST).

### TanStack Start

The `tanstackStartRouteHandlerAdapter` follows the same pattern:

```typescript
// app/routes/api/bot/$adapter/$botId.ts
import { tanstackStartRouteHandlerAdapter } from '@igniter-js/bot';

export const { GET, POST } = tanstackStartRouteHandlerAdapter(bots);
```

### Express / Fastify / Hono / Any HTTP Framework

Bot adapters work with any framework through the standard `Request`/`Response` API:

```typescript
// Express example
app.post('/api/bot/:adapter', async (req, res) => {
  const webResponse = await bot.handle(req.params.adapter, toWebRequest(req));
  res.status(webResponse.status);
  // Forward headers and body...
});
```

See the [Framework Integration](/docs/bots/framework-integration) guide for complete examples with Express, Fastify, Hono, and more.

***

## Environment Variables Reference

Bot adapters read from environment variables as defaults. You only need to pass config values explicitly when the env vars differ.

| Variable                  | Used By  | Description                           |
| ------------------------- | -------- | ------------------------------------- |
| `TELEGRAM_TOKEN`          | Telegram | Bot API token                         |
| `TELEGRAM_WEBHOOK_URL`    | Telegram | Webhook endpoint URL                  |
| `TELEGRAM_WEBHOOK_SECRET` | Telegram | Webhook secret token                  |
| `WHATSAPP_TOKEN`          | WhatsApp | Cloud API access token                |
| `WHATSAPP_PHONE`          | WhatsApp | Phone number ID                       |
| `DISCORD_TOKEN`           | Discord  | Bot token                             |
| `DISCORD_APP_ID`          | Discord  | Application ID                        |
| `DISCORD_PUBLIC_KEY`      | Discord  | Public key for signature verification |

***

## Next Steps

<Cards>
  <Card title="Quick Start" description="Build your first multi-platform bot in under 3 minutes." href="/docs/bots/quick-start" />

  <Card title="Core Concepts" description="Understand the builder, adapters, commands, and middleware pipeline." href="/docs/bots/core-concepts" />

  <Card title="Adapters" description="Deep dive into each platform adapter with full configuration reference." href="/docs/bots/adapters" />
</Cards>


---

# Middlewares

> Secure, rate-limit, and monitor your bot with built-in middlewares. Create custom middleware for authentication, logging, and request enrichment.
URL: https://igniterjs.com/docs/bots/middlewares

## Middlewares

Middlewares execute in sequence for every incoming message. They can **enrich the context**, **block requests**, or **perform side effects** like logging and analytics. The framework ships with three production-ready middlewares and a flexible API for custom ones.

***

## Middleware Contract

```typescript
type Middleware<TContextIn, TContextOut> = (
  ctx: TContextIn,
  next: () => Promise<void>,
) => Promise<void | Partial<TContextOut>>;
```

| Action             | How                                                            |
| ------------------ | -------------------------------------------------------------- |
| **Pass control**   | Call `await next()`                                            |
| **Block request**  | Don't call `next()` — pipeline stops here                      |
| **Enrich context** | Return an object — merged into context for downstream handlers |
| **Side effects**   | Do work before and/or after `next()`                           |
| **Error handling** | Wrap `next()` in try/catch                                     |

***

## Built-in Middlewares

### Auth Middleware

Controls access based on user IDs, channel IDs, custom logic, or roles.

```typescript
import { authMiddleware, authPresets, roleMiddleware } from '@igniter-js/bot';
```

#### Basic Usage

```typescript
// Allow only specific users
builder.addMiddleware(authMiddleware({
  allowedUsers: ['user_123', 'user_456'],
  unauthorizedMessage: '⛔ You are not authorized.',
}));

// Block specific users
builder.addMiddleware(authMiddleware({
  blockedUsers: ['spammer_789'],
}));

// Allow only in specific channels
builder.addMiddleware(authMiddleware({
  allowedChannels: ['channel_support', 'channel_vip'],
}));
```

#### Custom Authorization

```typescript
builder.addMiddleware(authMiddleware({
  checkFn: async (ctx) => {
    const user = await database.getUser(ctx.message.author.id);
    return user?.plan === 'premium'; // Only premium users
  },
  unauthorizedMessage: (ctx) => `Upgrade to premium, ${ctx.message.author.name}!`,
  skip: (ctx) => ctx.message.content?.type === 'command' && ctx.message.content.command === 'help',
  onUnauthorized: async (ctx) => {
    await analytics.track('unauthorized_access', { userId: ctx.message.author.id });
  },
}));
```

| Option                | Type                                   | Description                        |
| --------------------- | -------------------------------------- | ---------------------------------- |
| `allowedUsers`        | `string[]`                             | Only these user IDs can access     |
| `allowedChannels`     | `string[]`                             | Only these channel IDs are active  |
| `blockedUsers`        | `string[]`                             | These user IDs are blocked         |
| `blockedChannels`     | `string[]`                             | These channel IDs are blocked      |
| `checkFn`             | `(ctx) => boolean \| Promise<boolean>` | Custom authorization logic         |
| `unauthorizedMessage` | `string \| (ctx) => string`            | Message sent on denial             |
| `skip`                | `(ctx) => boolean \| Promise<boolean>` | Skip auth under certain conditions |
| `onUnauthorized`      | `(ctx) => void \| Promise<void>`       | Custom handler for denied access   |

#### Role-Based Auth

```typescript
builder.addMiddleware(roleMiddleware({
  getRoles: async (userId) => {
    const user = await db.users.findById(userId);
    return user?.roles ?? [];
  },
  requiredRoles: ['admin', 'moderator'],
  unauthorizedMessage: '🔒 Admins and moderators only.',
}));
```

#### Pre-built Presets

```typescript
// Admin-only bot
builder.addMiddleware(authPresets.adminsOnly(['admin_001', 'admin_002']));

// Private chat only
builder.addMiddleware(authPresets.privateOnly());

// Group chat only
builder.addMiddleware(authPresets.groupsOnly());

// Whitelist
builder.addMiddleware(authPresets.whitelist(['user_a', 'user_b']));

// Blacklist
builder.addMiddleware(authPresets.blacklist(['spammer_x']));
```

***

### Rate Limit Middleware

Prevents abuse by limiting the number of requests per user within a time window.

```typescript
import { rateLimitMiddleware, rateLimitPresets, memoryRateLimitStore } from '@igniter-js/bot';
```

#### Basic Usage

```typescript
builder.addMiddleware(rateLimitMiddleware({
  maxRequests: 10,
  windowMs: 60_000, // 1 minute
  message: '⚠️ Too many requests. Please wait a minute.',
}));
```

| Option           | Type                                         | Default                | Description                  |
| ---------------- | -------------------------------------------- | ---------------------- | ---------------------------- |
| `maxRequests`    | `number`                                     | Required               | Max requests in the window   |
| `windowMs`       | `number`                                     | Required               | Time window in milliseconds  |
| `store`          | `RateLimitStore`                             | `MemoryRateLimitStore` | Storage backend              |
| `keyGenerator`   | `(ctx) => string`                            | `provider:userId`      | Custom key for rate limiting |
| `message`        | `string \| (ctx, retryAfter) => string`      | Default message        | Response on limit exceeded   |
| `skip`           | `(ctx) => boolean \| Promise<boolean>`       | —                      | Skip rate limiting           |
| `onLimitReached` | `(ctx, retryAfter) => void \| Promise<void>` | —                      | Custom handler               |

#### Custom Key Generator

Rate limit by a combination of provider, user, and command:

```typescript
builder.addMiddleware(rateLimitMiddleware({
  maxRequests: 3,
  windowMs: 10_000, // 10 seconds
  keyGenerator: (ctx) => {
    const cmd = ctx.message.content?.type === 'command'
      ? ctx.message.content.command
      : 'message';
    return `${ctx.provider}:${ctx.message.author.id}:${cmd}`;
  },
  message: (ctx, retryAfter) =>
    `Command rate limit reached. Try again in ${retryAfter}s.`,
}));
```

#### Redis Store

For production, use a shared store like Redis:

```typescript
import { RateLimitStore } from '@igniter-js/bot';

class RedisRateLimitStore implements RateLimitStore {
  constructor(private redis: Redis) {}

  async get(key: string): Promise<number> {
    return parseInt(await this.redis.get(key) || '0');
  }

  async increment(key: string, windowMs: number): Promise<number> {
    const count = await this.redis.incr(key);
    await this.redis.pexpire(key, windowMs);
    return count;
  }

  async reset(key: string): Promise<void> {
    await this.redis.del(key);
  }
}

builder.addMiddleware(rateLimitMiddleware({
  maxRequests: 20,
  windowMs: 60_000,
  store: new RedisRateLimitStore(redisClient),
}));
```

#### Pre-built Presets

```typescript
// Strict: 5 req/min
builder.addMiddleware(rateLimitPresets.strict());

// Moderate: 10 req/min
builder.addMiddleware(rateLimitPresets.moderate());

// Lenient: 20 req/min
builder.addMiddleware(rateLimitPresets.lenient());

// Per-command: 3 req/10s per command
builder.addMiddleware(rateLimitPresets.perCommand());
```

***

### Logging Middleware

Structured logging for messages, commands, errors, and performance metrics.

```typescript
import { loggingMiddleware, loggingPresets, commandLoggingMiddleware } from '@igniter-js/bot';
```

#### Basic Usage

```typescript
builder.addMiddleware(loggingMiddleware({
  logMessages: true,
  logCommands: true,
  logErrors: true,
  logMetrics: true,
  includeUserInfo: true,
  includeContent: false, // Security: don't log message content
}));
```

| Option            | Type                           | Default        | Description                             |
| ----------------- | ------------------------------ | -------------- | --------------------------------------- |
| `logger`          | `BotLogger`                    | `console`      | Logger instance (Pino, Winston, etc.)   |
| `logMessages`     | `boolean`                      | `true`         | Log incoming messages                   |
| `logCommands`     | `boolean`                      | `true`         | Log command executions                  |
| `logErrors`       | `boolean`                      | `true`         | Log errors                              |
| `logMetrics`      | `boolean`                      | `true`         | Log execution time                      |
| `includeUserInfo` | `boolean`                      | `true`         | Include user id/username                |
| `includeContent`  | `boolean`                      | `false`        | Include message content (security risk) |
| `formatter`       | `(ctx, event, data) => string` | Default format | Custom log format                       |
| `skip`            | `(ctx) => boolean`             | —              | Skip logging conditions                 |

#### With Structured Logger

```typescript
import pino from 'pino';

const logger = pino({ level: 'info' });

builder.addMiddleware(loggingMiddleware({
  logger,
  logMessages: true,
  logMetrics: true,
  includeUserInfo: true,
  includeContent: false,
}));
```

The middleware calls `logger.info()`, `logger.debug()`, `logger.warn()`, and `logger.error()` — compatible with any logger implementing the `BotLogger` interface.

#### Pre-built Presets

```typescript
// Minimal: only errors
builder.addMiddleware(loggingPresets.minimal());

// Standard: messages, commands, errors
builder.addMiddleware(loggingPresets.standard());

// Verbose: everything including metrics and content
builder.addMiddleware(loggingPresets.verbose());

// Production: standard logging without PII
builder.addMiddleware(loggingPresets.production());

// Debug: full JSON output for troubleshooting
builder.addMiddleware(loggingPresets.debug());
```

#### Command-Specific Logging

For detailed per-command logs with parameters:

```typescript
builder.addMiddleware(commandLoggingMiddleware({
  logger: pino(),
  includeParams: true,
}));

// Output:
// [COMMAND] /search by @username
// [PARAMS] ["typescript books"]
// [SUCCESS] /search completed in 45ms
```

***

## Custom Middleware

### Context Enrichment

Add properties to the context for downstream handlers:

```typescript
builder.addMiddleware(async (ctx, next) => {
  const user = await db.users.findById(ctx.message.author.id);
  await next();
  return { user }; // ctx.user now available in all subsequent handlers
});
```

### Timing & Performance

```typescript
builder.addMiddleware(async (ctx, next) => {
  const start = performance.now();
  try {
    await next();
  } finally {
    const ms = performance.now() - start;
    metrics.histogram('bot.request.duration', ms, {
      provider: ctx.provider,
      command: ctx.message.content?.type === 'command' ? ctx.message.content.command : 'message',
    });
  }
});
```

### Feature Flags

```typescript
builder.addMiddleware(async (ctx, next) => {
  const flags = await featureFlags.getForUser(ctx.message.author.id);

  if (!flags.newSearchEnabled && ctx.message.content?.type === 'command' && ctx.message.content.command === 'search') {
    await ctx.reply('The new search feature is not available for your account yet.');
    return; // Block pipeline
  }

  await next();
});
```

### Error Boundary

```typescript
builder.addMiddleware(async (ctx, next) => {
  try {
    await next();
  } catch (error) {
    await errorTracking.captureException(error, {
      userId: ctx.message.author.id,
      provider: ctx.provider,
      command: ctx.message.content?.type === 'command' ? ctx.message.content.command : undefined,
    });
    await ctx.reply('⚠️ An unexpected error occurred. Our team has been notified.');
    // Don't re-throw — gracefully handled
  }
});
```

***

## Middleware Ordering Matters

The order you add middlewares determines the execution order:

```
1. Logging middleware      → Logs before/after everything
2. Rate limit middleware   → Check limits early
3. Auth middleware         → Block unauthorized users
4. Custom enrichment       → Load user/profile data
5. Command handler         → Execute the command
```

```typescript
builder
  .addMiddleware(loggingPresets.production())     // 1st: log everything
  .addMiddleware(rateLimitPresets.moderate())      // 2nd: check rate limits
  .addMiddleware(authPresets.whitelist(['...']))   // 3rd: auth check
  .addMiddleware(async (ctx, next) => {            // 4th: enrich context
    const user = await loadUser(ctx.message.author.id);
    await next();
    return { user };
  });
```

<Callout type="warn">
  Place **rate limiting before auth** so that rate limits apply to unauthorized users too — otherwise attackers can bypass rate limits by triggering auth failures.
</Callout>

***

## Next Steps

<Cards>
  <Card title="Plugins" description="Package commands, middlewares, and hooks into reusable modules." href="/docs/bots/plugins" />

  <Card title="Sessions" description="Persist conversational state across messages." href="/docs/bots/sessions" />

  <Card title="Best Practices" description="Production patterns, security, and performance tips." href="/docs/bots/best-practices" />
</Cards>


---

# Plugins

> Extend your bot with modular plugins. Package commands, middlewares, adapters, and lifecycle hooks into reusable, shareable modules.
URL: https://igniterjs.com/docs/bots/plugins

## Plugins

Plugins are the **modular extension system** for `@igniter-js/bot`. A plugin packages commands, middlewares, adapters, and lifecycle hooks into a single, reusable module that can be shared across bots and projects.

***

## Plugin Contract

```typescript
interface BotPlugin {
  name: string                      // Unique plugin name
  version: string                   // Semver version
  description?: string              // What the plugin does
  commands?: Record<string, BotCommand>       // Commands to register
  middlewares?: Middleware<any, any>[]         // Middlewares to add
  adapters?: Record<string, IBotAdapter<any>> // Adapters to register
  hooks?: {
    onStart?: () => Promise<void> | void
    onMessage?: (ctx: BotContext) => Promise<void> | void
    onError?: (ctx: BotContext & { error: BotError }) => Promise<void> | void
    onStop?: () => Promise<void> | void
  }
  config?: Record<string, any>      // Plugin-specific configuration
}
```

When a plugin is loaded via `.usePlugin()`, the builder automatically:

1. Registers all plugin commands
2. Appends all plugin middlewares to the pipeline
3. Registers all plugin adapters
4. Attaches all lifecycle hooks to the bot

***

## Built-in Plugin: Analytics

The `analyticsPlugin` tracks bot usage metrics and provides a `/stats` command.

### Installation

```typescript
import { analyticsPlugin } from '@igniter-js/bot';
```

### Basic Usage

```typescript
const bot = IgniterBot.create()
  .usePlugin(analyticsPlugin())
  .build();
```

This enables basic console-logged analytics and the `/stats` command:

```
/stats

📊 Bot Statistics

Messages: 1,247
Commands: 342
Errors: 3
Unique Users: 89
```

### With External Analytics Service

```typescript
import { analyticsPlugin } from '@igniter-js/bot';
import { PostHog } from 'posthog-node';

const posthog = new PostHog(process.env.POSTHOG_API_KEY!);

const bot = IgniterBot.create()
  .usePlugin(analyticsPlugin({
    trackEvent: async (event, properties) => {
      await posthog.capture({
        distinctId: properties.userId || 'anonymous',
        event,
        properties,
      });
    },
    trackMessages: true,
    trackCommands: true,
    trackErrors: true,
    includeUserInfo: true,
  }))
  .build();
```

| Option            | Type                                      | Default       | Description                  |
| ----------------- | ----------------------------------------- | ------------- | ---------------------------- |
| `trackEvent`      | `(event, props) => void \| Promise<void>` | `console.log` | Where to send events         |
| `trackMessages`   | `boolean`                                 | `true`        | Track message events         |
| `trackCommands`   | `boolean`                                 | `true`        | Track command events         |
| `trackErrors`     | `boolean`                                 | `true`        | Track error events           |
| `includeUserInfo` | `boolean`                                 | `true`        | Include user ID and username |

### Events Tracked

| Event         | Properties                                                      | When                         |
| ------------- | --------------------------------------------------------------- | ---------------------------- |
| `bot.started` | `timestamp`                                                     | Bot initialization           |
| `bot.message` | `provider, contentType, isGroup, isMentioned, userId, username` | Every incoming message       |
| `bot.command` | Same as message + `command, params`                             | Every command execution      |
| `bot.error`   | `provider, errorMessage, errorCode, userId`                     | Every error caught           |
| `bot.request` | `provider, event, duration, isGroup`                            | After every request (timing) |

***

## Creating Custom Plugins

### Example: Welcome Plugin

A plugin that sends a welcome message to new users:

```typescript
// plugins/welcome.ts
import type { BotPlugin } from '@igniter-js/bot';

export function welcomePlugin(options?: {
  message?: string;
  trackNewUsers?: boolean;
}): BotPlugin {
  const { message = 'Welcome to the bot! 👋', trackNewUsers = true } = options || {};

  const seenUsers = new Set<string>();

  return {
    name: 'welcome',
    version: '1.0.0',
    description: 'Sends a welcome message to new users',

    middlewares: [
      async (ctx, next) => {
        const userId = ctx.message.author.id;

        if (!seenUsers.has(userId)) {
          seenUsers.add(userId);
          await ctx.reply(message);

          if (trackNewUsers) {
            console.log(`New user: ${ctx.message.author.username} on ${ctx.provider}`);
          }
        }

        await next();
      },
    ],
  };
}
```

Use it:

```typescript
import { welcomePlugin } from './plugins/welcome';

const bot = IgniterBot.create()
  .usePlugin(welcomePlugin({
    message: '🎉 Welcome to our community! Type /help to get started.',
    trackNewUsers: true,
  }))
  .build();
```

### Example: Scheduled Tasks Plugin

A plugin that runs periodic tasks:

```typescript
// plugins/scheduler.ts
import type { BotPlugin } from '@igniter-js/bot';

export function schedulerPlugin(options: {
  intervalMs: number;
  task: () => Promise<void>;
}): BotPlugin {
  return {
    name: 'scheduler',
    version: '1.0.0',
    description: 'Runs periodic background tasks',

    hooks: {
      onStart: () => {
        setInterval(async () => {
          try {
            await options.task();
          } catch (error) {
            console.error('[scheduler] Task failed:', error);
          }
        }, options.intervalMs);
      },
    },
  };
}
```

### Example: Multi-Tenant Plugin

A plugin that adds tenant-aware middleware and a tenant command:

```typescript
// plugins/multi-tenant.ts
import type { BotPlugin, BotContext } from '@igniter-js/bot';

export function multiTenantPlugin(options: {
  getTenant: (userId: string) => Promise<string>;
}): BotPlugin {
  return {
    name: 'multi-tenant',
    version: '1.0.0',
    description: 'Adds multi-tenant context to bot interactions',

    middlewares: [
      async (ctx, next) => {
        const tenantId = await options.getTenant(ctx.message.author.id);
        await next();
        return { tenantId }; // Available in downstream handlers
      },
    ],

    commands: {
      tenant: {
        name: 'tenant',
        aliases: ['workspace'],
        description: 'Show current tenant',
        help: 'Use /tenant to see your current workspace',
        async handle(ctx) {
          const tenantId = (ctx as any).tenantId || 'unknown';
          await ctx.reply(`🏢 Current workspace: **${tenantId}**`);
        },
      },
    },
  };
}
```

***

## Plugin Factories

Plugins can be factories that accept configuration:

```typescript
type BotPluginFactory<TConfig = any> = (config?: TConfig) => BotPlugin;

// Usage
const plugin = myPlugin({ apiKey: '...', environment: 'production' });
builder.usePlugin(plugin);
```

***

## Composing Multiple Plugins

Plugins are loaded in order and their middlewares are appended to the pipeline:

```typescript
const bot = IgniterBot.create()
  .usePlugin(welcomePlugin({ message: 'Hello!' }))    // 1st
  .usePlugin(analyticsPlugin({ trackMessages: true })) // 2nd
  .usePlugin(multiTenantPlugin({ getTenant }))         // 3rd
  .build();

// Middleware order: welcome → analytics → multi-tenant → your custom middlewares → commands
```

<Callout type="info">
  Plugin middlewares are appended **before** `.build()` returns, but **after** any middlewares already added via `.addMiddleware()`. If order matters, add your middlewares after loading plugins.
</Callout>

***

## Next Steps

<Cards>
  <Card title="Sessions" description="Persist conversational state with memory, Redis, or custom stores." href="/docs/bots/sessions" />

  <Card title="Framework Integration" description="Wire up your bot with Next.js, Express, and Fastify." href="/docs/bots/framework-integration" />

  <Card title="Real-World Examples" description="Complete production bot scenarios with code." href="/docs/bots/real-world" />
</Cards>


---

# Quick Start

> Build a production-ready multi-platform bot in 3 minutes. Covers Telegram, WhatsApp, and Discord with a complete example.
URL: https://igniterjs.com/docs/bots/quick-start

## Quick Start

This guide walks you through building a **multi-platform bot** that responds to commands on Telegram, WhatsApp, and Discord — all from the same codebase. By the end, you'll have a bot with commands, middleware, and session management running in production.

<Callout type="info">
  This guide assumes you have a Next.js project. The same patterns work with Express, Fastify, Hono, or any Node.js framework — see [Framework Integration](/docs/bots/framework-integration).
</Callout>

***

## Step 1: Install Dependencies

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/bot zod
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/bot zod
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/bot zod
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/bot zod
    ```
  </Tab>
</Tabs>

***

## Step 2: Set Up Environment Variables

Create a `.env.local` file:

```bash
# Telegram
TELEGRAM_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

# WhatsApp (Cloud API)
WHATSAPP_TOKEN=EAAx...
WHATSAPP_PHONE=1234567890

# Discord
DISCORD_TOKEN=MTIz...
DISCORD_APP_ID=123456789012345678
DISCORD_PUBLIC_KEY=abc123...
```

<Callout type="warn">
  Never commit `.env.local` to version control. Add it to `.gitignore`.
</Callout>

***

## Step 3: Create Your Bot

Create `lib/bot.ts`:

```typescript
import {
  IgniterBot,
  telegram,
  whatsapp,
  discord,
  memoryStore,
  loggingMiddleware,
  rateLimitMiddleware,
  analyticsPlugin,
} from '@igniter-js/bot';

export const bot = IgniterBot
  .create()
  // Identity — auto-generates id and name from handle
  .withHandle('@assistant_bot')

  // Session storage for conversational state
  .withSessionStore(memoryStore())

  // Structured logging (Pino, Winston, or console)
  .withLogger({
    info: (...args) => console.log('[bot]', ...args),
    error: (...args) => console.error('[bot]', ...args),
    debug: (...args) => console.debug('[bot]', ...args),
    warn: (...args) => console.warn('[bot]', ...args),
  })

  // All platforms at once
  .addAdapters({
    telegram: telegram({ token: process.env.TELEGRAM_TOKEN! }),
    whatsapp: whatsapp({
      token: process.env.WHATSAPP_TOKEN!,
      phone: process.env.WHATSAPP_PHONE!,
    }),
    discord: discord({
      token: process.env.DISCORD_TOKEN!,
      applicationId: process.env.DISCORD_APP_ID!,
      publicKey: process.env.DISCORD_PUBLIC_KEY!,
    }),
  })

  // Middleware — runs for every message
  .addMiddlewares([
    loggingMiddleware({
      logMessages: true,
      logCommands: true,
      logMetrics: true,
      includeUserInfo: true,
    }),
    rateLimitMiddleware({
      maxRequests: 10,
      windowMs: 60_000, // 1 minute
      message: '⚠️ Please slow down. Try again in a minute.',
    }),
  ])

  // Commands
  .addCommand('start', {
    name: 'start',
    aliases: ['hello', 'hi'],
    description: 'Start the bot',
    help: 'Use /start to begin interacting with the bot',
    async handle(ctx) {
      await ctx.reply(
        `👋 Welcome, ${ctx.message.author.name}!\n\n` +
        `I'm running on **${ctx.provider}**.\n\n` +
        `Type /help to see what I can do.`,
      );
    },
  })
  .addCommand('help', {
    name: 'help',
    aliases: ['commands', '?'],
    description: 'Show available commands',
    help: 'Use /help to see the list of commands',
    async handle(ctx) {
      await ctx.reply(
        `📋 **Available Commands**\n\n` +
        `/start — Start the bot\n` +
        `/help — Show this message\n` +
        `/echo &lt;text&gt; — Repeat your message\n` +
        `/ping — Check bot responsiveness\n` +
        `/image — Send a sample image\n` +
        `/buttons — Show interactive buttons\n` +
        `/session — Test session persistence`,
      );
    },
  })
  .addCommand('echo', {
    name: 'echo',
    aliases: ['say', 'repeat'],
    description: 'Echo back your message',
    help: 'Use /echo &lt;text&gt; to repeat your message',
    async handle(ctx) {
      const message = ctx.message.content;
      const text = message?.type === 'command'
        ? message.params.join(' ')
        : 'Nothing to echo!';

      if (!text.trim()) {
        await ctx.reply('Please provide some text. Example: `/echo Hello World`');
        return;
      }

      await ctx.reply(`🔊 ${text}`);
    },
  })
  .addCommand('ping', {
    name: 'ping',
    aliases: [],
    description: 'Check bot latency',
    help: 'Use /ping to check if the bot is responsive',
    async handle(ctx) {
      const start = Date.now();
      await ctx.reply(`🏓 Pong! \`${Date.now() - start}ms\``);
    },
  })
  .addCommand('image', {
    name: 'image',
    aliases: ['pic', 'photo'],
    description: 'Send a sample image',
    help: 'Use /image to receive a sample image',
    async handle(ctx) {
      await ctx.replyWithImage(
        'https://placekitten.com/400/300',
        'Here is a random kitten! 🐱',
      );
    },
  })
  .addCommand('buttons', {
    name: 'buttons',
    aliases: [],
    description: 'Show interactive buttons',
    help: 'Use /buttons to see interactive elements',
    async handle(ctx) {
      await ctx.replyWithButtons('Choose an option:', [
        { id: 'btn_1', label: 'Option A', action: 'callback', data: 'selected_a' },
        { id: 'btn_2', label: 'Option B', action: 'callback', data: 'selected_b' },
        { id: 'btn_3', label: 'Visit Website', action: 'url', data: { url: 'https://example.com' } },
      ]);
    },
  })
  .addCommand('session', {
    name: 'session',
    aliases: [],
    description: 'Test session persistence',
    help: 'Use /session to see your conversation state',
    async handle(ctx) {
      const count = (ctx.session.data.visitCount || 0) + 1;
      await ctx.session.update({ visitCount: count });
      await ctx.reply(
        `📊 You've used the /session command **${count}** time(s) in this chat.`,
      );
    },
  })

  // Event handlers
  .onMessage(async (ctx) => {
    // Called for every non-command message
    console.log(`[message] ${ctx.provider} | ${ctx.message.author.name}`);
  })
  .onError(async (ctx) => {
    // Called when an error occurs in any handler
    console.error(`[error]`, ctx.error);
    await ctx.reply('⚠️ Something went wrong. Please try again.');
  })
  .onStart(async () => {
    console.log('✅ Bot started successfully!');
  })

  // Analytics plugin — tracks usage metrics
  .usePlugin(analyticsPlugin({
    trackMessages: true,
    trackCommands: true,
    trackErrors: true,
  }))

  // Build it!
  .build();

// Start adapters (registers webhooks, commands, etc.)
await bot.start();
```

✅ **Your bot is now initialized.** The `.start()` call registers webhooks (Telegram), syncs commands (Discord), and runs startup hooks.

***

## Step 4: Create the API Route

Create a route that bridges incoming webhook requests to your bot:

### Next.js App Router

```typescript
// app/api/bot/[adapter]/[botId]/route.ts
import { nextRouteHandlerAdapter } from '@igniter-js/bot';
import { bot } from '@/lib/bot';

export const { GET, POST } = nextRouteHandlerAdapter({
  assistant_bot: bot,
});
```

The adapter expects these dynamic segments:

* `[adapter]` — `telegram`, `whatsapp`, or `discord`
* `[botId]` — matches the bot's `id` (derived from handle: `assistant_bot`)

### Test Locally

For local development with Telegram, use a tunneling service:

```bash
# Install ngrok or localtunnel
npx localtunnel --port 3000 --subdomain my-bot-dev

# Then set your Telegram webhook URL to:
# https://my-bot-dev.loca.lt/api/bot/telegram/assistant_bot
```

***

## Step 5: Verify Everything Works

<Steps>
  <Step>
    ### Test on Telegram

    Open your bot on Telegram and type:

    ```
    /start
    /help
    /ping
    /echo Hello from Igniter!
    /image
    /buttons
    ```

    Each command should respond immediately with the appropriate reply.
  </Step>

  <Step>
    ### Test Session Persistence

    Type `/session` multiple times — the counter should increment:

    ```
    /session  →  "You've used the /session command 1 time(s)"
    /session  →  "You've used the /session command 2 time(s)"
    ```
  </Step>

  <Step>
    ### Test Rate Limiting

    Send more than 10 messages in one minute — you should see:

    ```
    ⚠️ Please slow down. Try again in a minute.
    ```
  </Step>
</Steps>

***

## What's Next?

Your bot is running with:

* ✅ **3 platforms** (Telegram, WhatsApp, Discord)
* ✅ **6 commands** with help text and aliases
* ✅ **Logging middleware** with structured output
* ✅ **Rate limiting** with configurable limits
* ✅ **Session persistence** with in-memory store
* ✅ **Analytics tracking** for usage metrics
* ✅ **Error handling** with graceful recovery

<Cards>
  <Card title="Commands" description="Master aliases, subcommands, Zod validation, and command groups." href="/docs/bots/commands" />

  <Card title="Adapters" description="Deep dive into each platform's capabilities, config, and best practices." href="/docs/bots/adapters" />

  <Card title="Middlewares" description="Learn auth, rate-limiting, logging patterns, and custom middleware." href="/docs/bots/middlewares" />

  <Card title="Sessions" description="Persistent state management with memory, Redis, or custom stores." href="/docs/bots/sessions" />
</Cards>


---

# Real-World Examples

> Production-grade bot examples with complete code. Customer support, e-commerce, community management, onboarding flows, and more.
URL: https://igniterjs.com/docs/bots/real-world

## Real-World Examples

Complete, production-ready bot scenarios showing how `@igniter-js/bot` solves real problems. Each example is self-contained and can be adapted for your use case.

***

## 1. Customer Support Bot (Multi-Platform)

A support bot that routes inquiries across Telegram, WhatsApp, and Discord with session tracking and human escalation.

### Features

* Multi-platform (Telegram + WhatsApp + Discord)
* Ticket creation with session tracking
* FAQ self-service
* Escalation to human agents
* Proactive status updates

```typescript
// lib/bot.ts
import { IgniterBot, telegram, whatsapp, discord, memoryStore } from '@igniter-js/bot';
import { supportCommands } from './commands/support';
import { supportMiddleware } from './middleware/support';

export const supportBot = IgniterBot.create()
  .withHandle('@support_bot')
  .withSessionStore(memoryStore())
  .addAdapters({
    telegram: telegram({ token: process.env.TELEGRAM_TOKEN! }),
    whatsapp: whatsapp({ token: process.env.WHATSAPP_TOKEN!, phone: process.env.WHATSAPP_PHONE! }),
    discord: discord({ token: process.env.DISCORD_TOKEN!, applicationId: process.env.DISCORD_APP_ID! }),
  })
  .addMiddlewares([supportMiddleware])
  .addCommands(supportCommands)
  .onError(async (ctx) => {
    await ctx.reply('Our support system encountered an error. A human agent will assist you shortly.');
  })
  .build();

await supportBot.start();
```

```typescript
// commands/support.ts
export const supportCommands = {
  help: Bot.command({
    name: 'help',
    aliases: ['support', 'faq'],
    description: 'Get help',
    help: 'Use /help to see support options',
    async handle(ctx) {
      await ctx.replyWithButtons('How can we help?', [
        { id: 'faq_order', label: '📦 Order Issues', action: 'callback', data: 'faq_order' },
        { id: 'faq_account', label: '👤 Account Help', action: 'callback', data: 'faq_account' },
        { id: 'faq_billing', label: '💳 Billing', action: 'callback', data: 'faq_billing' },
      ]);
    },
  }),

  ticket: Bot.command({
    name: 'ticket',
    aliases: ['report', 'issue'],
    description: 'Create a support ticket',
    help: 'Use /ticket &lt;description&gt; to report an issue',
    async handle(ctx) {
      const ticketId = await createSupportTicket({
        userId: ctx.message.author.id,
        platform: ctx.provider,
        description: ctx.args.description,
      });

      await ctx.session.update({ activeTicket: ticketId });
      await ctx.reply(
        `✅ Ticket **#${ticketId}** created!\n\n` +
        `We'll respond within 24 hours. Reply to this message to add more details.`,
      );
    },
  }),

  status: Bot.command({
    name: 'status',
    aliases: ['check'],
    description: 'Check ticket status',
    help: 'Use /status to check your open tickets',
    async handle(ctx) {
      const tickets = await getOpenTickets(ctx.message.author.id);

      if (tickets.length === 0) {
        await ctx.reply('You have no open tickets.');
        return;
      }

      const statusList = tickets.map(t =>
        `**#${t.id}** — ${t.status} — ${t.subject}`
      ).join('\n');

      await ctx.reply(`📋 **Your Open Tickets:**\n\n${statusList}`);
    },
  }),
};
```

```typescript
// middleware/support.ts
export const supportMiddleware = async (ctx, next) => {
  // If there's an active ticket, append messages to it
  const activeTicket = ctx.session.data.activeTicket;

  if (activeTicket && ctx.message.content?.type === 'text') {
    await appendToTicket(activeTicket, {
      author: ctx.message.author.name,
      content: ctx.message.content.content,
      platform: ctx.provider,
    });
    await ctx.reply('✅ Message added to your ticket.');
    return; // Don't process as a command
  }

  await next();
};
```

***

## 2. E-Commerce Bot

A shopping bot with product search, cart management, and order tracking across platforms.

### Features

* Product catalog search
* Shopping cart with session persistence
* Order placement and tracking
* Interactive product browsing with buttons
* Multi-currency pricing

```typescript
// commands/shop.ts
import { z } from 'zod';
import { Bot } from '@igniter-js/bot';

export const shopCommands = {
  search: Bot.command({
    name: 'search',
    aliases: ['find', 'browse'],
    description: 'Search products',
    help: 'Use /search &lt;query&gt; to find products',
    args: z.object({ query: z.string().min(2) }),
    async handle(ctx, args) {
      await ctx.sendTyping!();

      const products = await searchProducts(args.query);

      if (products.length === 0) {
        await ctx.reply(`No products found for "${args.query}".`);
        return;
      }

      await ctx.session.update({ searchResults: products.slice(0, 10) });

      await ctx.replyWithButtons(
        `🔍 **${products.length}** results for "${args.query}":\n\n` +
        products.slice(0, 5).map((p, i) => `${i + 1}. **${p.name}** — $${p.price}`).join('\n'),
        products.slice(0, 5).map((p, i) => ({
          id: `add_${p.id}`,
          label: `🛒 Add ${p.name}`,
          action: 'callback' as const,
          data: p.id,
        })),
      );
    },
  }),

  cart: Bot.command({
    name: 'cart',
    aliases: ['basket'],
    description: 'View your cart',
    help: 'Use /cart to see items in your cart',
    async handle(ctx) {
      const cart = ctx.session.data.cart || [];

      if (cart.length === 0) {
        await ctx.reply('🛒 Your cart is empty. Use /search to find products.');
        return;
      }

      const total = cart.reduce((sum, item) => sum + item.price * item.quantity, 0);

      await ctx.replyWithButtons(
        `🛒 **Your Cart** (${cart.length} items)\n\n` +
        cart.map((item, i) =>
          `${i + 1}. ${item.name} ×${item.quantity} — $${item.price * item.quantity}`
        ).join('\n') +
        `\n\n**Total: $${total.toFixed(2)}**`,
        [
          { id: 'checkout', label: '💳 Checkout', action: 'callback', data: 'checkout' },
          { id: 'clear', label: '🗑 Clear Cart', action: 'callback', data: 'clear_cart' },
        ],
      );
    },
  }),

  checkout: Bot.command({
    name: 'checkout',
    aliases: ['buy', 'order'],
    description: 'Place your order',
    help: 'Use /checkout to complete your purchase',
    async handle(ctx) {
      const cart = ctx.session.data.cart || [];

      if (cart.length === 0) {
        await ctx.reply('Your cart is empty. Add items first with /search.');
        return;
      }

      const order = await createOrder({
        userId: ctx.message.author.id,
        items: cart,
        platform: ctx.provider,
      });

      await ctx.session.update({ cart: [], lastOrder: order.id });
      await ctx.reply(
        `✅ Order **#${order.id}** placed!\n\n` +
        `Total: $${order.total.toFixed(2)}\n` +
        `Track with: /track ${order.id}`,
      );
    },
  }),

  track: Bot.command({
    name: 'track',
    aliases: ['order'],
    description: 'Track an order',
    help: 'Use /track &lt;order_id&gt; to check status',
    args: z.object({ orderId: z.string() }),
    async handle(ctx, args) {
      const order = await getOrder(args.orderId);

      if (!order) {
        await ctx.reply('Order not found. Check the ID and try again.');
        return;
      }

      const statusEmoji = {
        processing: '📦',
        shipped: '🚚',
        delivered: '✅',
        cancelled: '❌',
      };

      await ctx.reply(
        `${statusEmoji[order.status]} Order **#${order.id}**\n\n` +
        `Status: **${order.status.toUpperCase()}**\n` +
        `Items: ${order.itemCount}\n` +
        `Placed: ${order.createdAt.toLocaleDateString()}`,
      );
    },
  }),
};
```

***

## 3. Community Moderation Bot

A Discord-first moderation bot with admin commands, welcome messages, and automated moderation.

### Features

* Admin command group with role-based access
* Welcome messages for new members
* Message logging
* Auto-moderation (banned words, spam detection)
* `/stats` for server analytics

```typescript
// lib/bot.ts
import { IgniterBot, discord, authMiddleware, roleMiddleware } from '@igniter-js/bot';

const bot = IgniterBot.create()
  .withHandle('@mod_bot')
  .addAdapter('discord', discord({
    token: process.env.DISCORD_TOKEN!,
    applicationId: process.env.DISCORD_APP_ID!,
    publicKey: process.env.DISCORD_PUBLIC_KEY!,
  }))
  .addMiddleware(roleMiddleware({
    getRoles: async (userId) => {
      const member = await discordApi.getGuildMember(process.env.GUILD_ID!, userId);
      return member.roles;
    },
    requiredRoles: ['admin', 'moderator'],
    unauthorizedMessage: '🔒 This command requires admin or moderator role.',
  }))
  .addCommandGroup('mod', {
    ban: {
      name: 'ban',
      aliases: [],
      description: 'Ban a user',
      help: 'Use /mod_ban &lt;user_id&gt; [reason]',
      async handle(ctx) {
        await banUser(ctx.args.userId, ctx.args.reason);
        await ctx.reply(`🚫 User ${ctx.args.userId} banned. Reason: ${ctx.args.reason || 'No reason provided'}`);
      },
    },
    kick: {
      name: 'kick',
      aliases: [],
      description: 'Kick a user',
      help: 'Use /mod_kick &lt;user_id&gt;',
      async handle(ctx) {
        await kickUser(ctx.args.userId);
        await ctx.reply(`👢 User ${ctx.args.userId} kicked.`);
      },
    },
    warn: {
      name: 'warn',
      aliases: [],
      description: 'Warn a user',
      help: 'Use /mod_warn &lt;user_id&gt; &lt;reason&gt;',
      async handle(ctx) {
        const warning = await addWarning(ctx.args.userId, ctx.args.reason);
        await ctx.reply(`⚠️ User ${ctx.args.userId} warned (${warning.count}/3). Reason: ${ctx.args.reason}`);
      },
    },
    clear: {
      name: 'clear',
      aliases: ['purge'],
      description: 'Clear messages',
      help: 'Use /mod_clear &lt;count&gt;',
      async handle(ctx) {
        await clearMessages(ctx.channel.id, ctx.args.count);
        await ctx.reply(`🧹 Cleared ${ctx.args.count} messages.`);
      },
    },
  })
  .build();
```

***

## 4. SaaS Onboarding Bot

A step-by-step onboarding bot that guides new users through setup.

### Features

* Multi-step guided flow
* Persistent session progress
* Input validation at each step
* Skip and reset capabilities
* Progress tracking

```typescript
// commands/onboarding.ts
export const onboardingCommands = {
  start: Bot.command({
    name: 'start',
    aliases: ['onboard', 'setup'],
    description: 'Start onboarding',
    help: 'Use /start to begin setting up your account',
    async handle(ctx) {
      await ctx.session.update({
        step: 1,
        data: { startedAt: new Date().toISOString() },
      });
      await ctx.reply(
        '🚀 **Welcome to Acme SaaS!**\n\n' +
        'I\'ll guide you through setup in 4 quick steps.\n\n' +
        '**Step 1/4:** What is your company name?',
      );
    },
  }),

  skip: Bot.command({
    name: 'skip',
    aliases: [],
    description: 'Skip current step',
    help: 'Use /skip to skip the current onboarding step',
    async handle(ctx) {
      const step = ctx.session.data.step;
      if (!step) {
        await ctx.reply('No onboarding in progress. Use /start to begin.');
        return;
      }
      await ctx.session.update({ step: step + 1 });
      await sendStepPrompt(ctx, step + 1);
    },
  }),

  reset: Bot.command({
    name: 'reset',
    aliases: ['restart'],
    description: 'Restart onboarding',
    help: 'Use /reset to restart the onboarding process',
    async handle(ctx) {
      await ctx.session.delete();
      await ctx.reply('🔄 Onboarding reset. Use /start to begin again.');
    },
  }),
};

// middleware/onboarding-flow.ts
export const onboardingFlowMiddleware = async (ctx, next) => {
  const step = ctx.session.data.step;

  // Only intercept non-command text messages during onboarding
  if (!step || ctx.message.content?.type === 'command') {
    return next();
  }

  const text = ctx.message.content?.type === 'text' ? ctx.message.content.content : '';

  switch (step) {
    case 1: // Company name
      if (!text.trim()) {
        await ctx.reply('Please enter a valid company name.');
        return;
      }
      await ctx.session.update({
        step: 2,
        data: { ...ctx.session.data, companyName: text },
      });
      await ctx.reply(
        '✅ Company: **' + text + '**\n\n' +
        '**Step 2/4:** What industry are you in?\n\n' +
        'Options: Tech, Retail, Healthcare, Finance, Education, Other',
      );
      return;

    case 2: // Industry
      const validIndustries = ['tech', 'retail', 'healthcare', 'finance', 'education', 'other'];
      if (!validIndustries.includes(text.toLowerCase())) {
        await ctx.reply('Please choose from: Tech, Retail, Healthcare, Finance, Education, Other');
        return;
      }
      await ctx.session.update({
        step: 3,
        data: { ...ctx.session.data, industry: text },
      });
      await ctx.reply(
        '✅ Industry: **' + text + '**\n\n' +
        '**Step 3/4:** How many team members will use Acme?',
      );
      return;

    case 3: // Team size
      const size = parseInt(text);
      if (isNaN(size) || size < 1) {
        await ctx.reply('Please enter a valid number (e.g., 5, 25, 100).');
        return;
      }
      await ctx.session.update({
        step: 4,
        data: { ...ctx.session.data, teamSize: size },
      });
      await ctx.replyWithButtons(
        '✅ Team size: **' + size + '** members\n\n' +
        '**Step 4/4:** Ready to complete setup?\n\n' +
        `Company: **${ctx.session.data.companyName}**\n` +
        `Industry: **${ctx.session.data.industry}**\n` +
        `Team: **${ctx.session.data.teamSize}** members`,
        [
          { id: 'confirm', label: '✅ Complete Setup', action: 'callback', data: 'confirm_onboarding' },
          { id: 'restart', label: '🔄 Start Over', action: 'callback', data: 'restart_onboarding' },
        ],
      );
      return;

    case 4:
      await ctx.reply('Please use the buttons above to confirm or restart.');
      return;
  }
};

async function sendStepPrompt(ctx, step) {
  const prompts = {
    1: '**Step 1/4:** What is your company name?',
    2: '**Step 2/4:** What industry are you in?',
    3: '**Step 3/4:** How many team members?',
    4: '**Step 4/4:** Confirm your setup with the buttons below.',
  };
  await ctx.reply(prompts[step] || 'Onboarding complete!');
}
```

***

## 5. Notification Service Bot

A bot that sends proactive notifications to users on their preferred platform.

### Features

* User preference management (preferred platform)
* Proactive push notifications
* Scheduled reminders
* Multi-channel delivery
* Notification templates

```typescript
// services/notifications.ts
import { bot } from '../lib/bot';

export async function sendOrderUpdate(userId: string, orderId: string, status: string) {
  const user = await getUserPreferences(userId);
  if (!user) return;

  const messages = {
    confirmed: '✅ Your order has been confirmed!',
    shipped: '🚚 Your order is on the way!',
    delivered: '📦 Your order has been delivered!',
    cancelled: '❌ Your order has been cancelled.',
  };

  await bot.send({
    provider: user.preferredPlatform,
    channel: user.platformChannelId,
    content: {
      type: 'interactive',
      text: `${messages[status]}\n\nOrder: **#${orderId}**`,
      buttons: [
        { id: 'track', label: '📍 Track', action: 'callback', data: `track_${orderId}` },
        { id: 'support', label: '🆘 Support', action: 'callback', data: `support_${orderId}` },
      ],
    },
  });
}

export async function sendDailyReminder(userId: string) {
  const user = await getUserPreferences(userId);
  if (!user) return;

  await bot.send({
    provider: user.preferredPlatform,
    channel: user.platformChannelId,
    content: {
      type: 'text',
      content: `☀️ Good morning, ${user.name}! Don't forget to check your tasks for today.`,
    },
  });
}

// Cron job (using node-cron or similar)
import cron from 'node-cron';

cron.schedule('0 9 * * *', async () => {
  const users = await getUsersWithReminders();
  for (const user of users) {
    await sendDailyReminder(user.id);
  }
});
```

***

## Architecture Pattern: Multi-Tenant Bot

A pattern for serving multiple organizations from a single bot instance:

```typescript
// lib/bot.ts
const bot = IgniterBot.create()
  .withHandle('@platform_bot')
  .addAdapters({
    telegram: telegram({ token: process.env.TELEGRAM_TOKEN! }),
    whatsapp: whatsapp({ token: process.env.WHATSAPP_TOKEN!, phone: process.env.WHATSAPP_PHONE! }),
  })
  .addMiddleware(async (ctx, next) => {
    // Resolve tenant from user mapping
    const tenant = await tenantResolver.resolve(ctx.message.author.id, ctx.provider);
    if (!tenant) {
      await ctx.reply('Your account is not associated with any organization.');
      return;
    }
    await next();
    return { tenant };
  })
  .addMiddleware(async (ctx, next) => {
    // Switch database context
    const db = await getTenantDatabase(ctx.tenant.id);
    await next();
    return { db };
  })
  .build();
```

***

## Next Steps

<Cards>
  <Card title="API Reference" description="Complete API documentation for all methods and types." href="/docs/bots/api-reference" />

  <Card title="Best Practices" description="Production patterns, security tips, and anti-patterns." href="/docs/bots/best-practices" />

  <Card title="Troubleshooting" description="Solve common errors and debug issues." href="/docs/bots/troubleshooting" />
</Cards>


---

# Sessions

> Persist conversational state across messages. Use in-memory storage for development, or plug in Redis, Prisma, or any custom backend for production.
URL: https://igniterjs.com/docs/bots/sessions

## Sessions

Sessions persist conversational state across multiple messages. They're essential for **multi-step workflows**, **form filling**, **shopping carts**, **onboarding flows**, and any interaction that spans more than one message.

***

## Architecture

```
Incoming Message
    ↓
Session Loader (auto-loads from store)
    ↓
Middleware Pipeline
    ↓
Command Handler (reads/writes ctx.session)
    ↓
Session Auto-Save (persists changes after handler completes)
```

Sessions are keyed by `userId:channelId` — each user has a separate session per chat.

***

## Quick Start

```typescript
import { IgniterBot, memoryStore } from '@igniter-js/bot';

const bot = IgniterBot.create()
  .withSessionStore(memoryStore())
  // ... adapters, commands, etc.
  .build();
```

Now every handler has access to `ctx.session`:

```typescript
builder.addCommand('start', {
  name: 'start',
  aliases: [],
  description: 'Start onboarding',
  help: 'Use /start to begin',
  async handle(ctx) {
    await ctx.session.update({ step: 'awaiting_name' });
    await ctx.reply('Welcome! What is your name?');
  },
});
```

***

## The BotSession Interface

```typescript
interface BotSession {
  userId: string          // Unique user identifier
  channelId: string       // Chat/channel identifier
  data: Record<string, any> // Your application state
  createdAt: Date         // Session creation timestamp
  updatedAt: Date         // Last update timestamp
  expiresAt?: Date        // Auto-cleanup on expiration
}
```

***

## BotSessionHelper (ctx.session)

The `ctx.session` object extends `BotSession` with convenience methods:

```typescript
interface BotSessionHelper extends BotSession {
  save(): Promise<void>
  delete(): Promise<void>
  update(data: Partial<Record<string, any>>): Promise<void>
}
```

| Method                               | Description                               |
| ------------------------------------ | ----------------------------------------- |
| `ctx.session.data`                   | Read current session state                |
| `ctx.session.update({ key: value })` | Merge data into the session and auto-save |
| `ctx.session.save()`                 | Explicitly persist the session            |
| `ctx.session.delete()`               | Remove the session from the store         |

***

## Multi-Step Workflow Example

A complete onboarding flow using sessions:

```typescript
builder.addCommand('onboard', {
  name: 'onboard',
  aliases: ['setup'],
  description: 'Start onboarding',
  help: 'Use /onboard to begin setup',
  async handle(ctx) {
    await ctx.session.update({ step: 'name', data: {} });
    await ctx.reply('Step 1/3: What is your name?');
  },
});

builder.addMiddleware(async (ctx, next) => {
  const step = ctx.session.data.step;

  if (!step || ctx.message.content?.type === 'command') {
    return next();
  }

  const text = ctx.message.content?.type === 'text'
    ? ctx.message.content.content
    : '';

  switch (step) {
    case 'name':
      await ctx.session.update({
        step: 'email',
        data: { ...ctx.session.data, name: text },
      });
      await ctx.reply(`Nice to meet you, ${text}! Step 2/3: What is your email?`);
      return; // Don't process commands during onboarding

    case 'email':
      await ctx.session.update({
        step: 'confirm',
        data: { ...ctx.session.data, email: text },
      });
      const data = ctx.session.data;
      await ctx.reply(
        `Step 3/3: Please confirm:\n\n` +
        `Name: **${data.name}**\n` +
        `Email: **${text}**\n\n` +
        `Type /confirm to save or /cancel to discard.`,
      );
      return;

    default:
      return next();
  }
});

builder.addCommand('confirm', {
  name: 'confirm',
  aliases: ['yes', 'ok'],
  description: 'Confirm onboarding data',
  help: 'Use /confirm to save your information',
  async handle(ctx) {
    if (ctx.session.data.step !== 'confirm') {
      await ctx.reply('No pending confirmation. Use /onboard to start.');
      return;
    }

    await saveUser(ctx.session.data);
    await ctx.session.delete();
    await ctx.reply('✅ Your profile has been saved! Welcome aboard.');
  },
});
```

***

## Memory Session Store

The built-in `MemorySessionStore` is suitable for **development and single-instance deployments**:

```typescript
import { memoryStore } from '@igniter-js/bot';

const store = memoryStore({
  cleanupIntervalMs: 60_000, // Clean expired sessions every 60 seconds (default)
});

builder.withSessionStore(store);
```

Features:

* In-memory `Map` storage — fast but ephemeral
* Automatic expired session cleanup
* `store.size()` to check active session count
* `store.destroy()` to stop cleanup interval

<Callout type="warn">
  Memory sessions are lost on process restart. For production, use a persistent store.
</Callout>

***

## Custom Session Stores

Implement the `BotSessionStore` interface to use any storage backend:

```typescript
interface BotSessionStore {
  get(userId: string, channelId: string): Promise<BotSession | null>
  set(userId: string, channelId: string, session: BotSession): Promise<void>
  delete(userId: string, channelId: string): Promise<void>
  clear(userId: string): Promise<void> // Delete all sessions for a user
}
```

### Redis Example

```typescript
import type { BotSessionStore, BotSession } from '@igniter-js/bot';
import { Redis } from 'ioredis';

class RedisSessionStore implements BotSessionStore {
  constructor(private redis: Redis, private prefix = 'bot:session:') {}

  private key(userId: string, channelId: string): string {
    return `${this.prefix}${userId}:${channelId}`;
  }

  async get(userId: string, channelId: string): Promise<BotSession | null> {
    const raw = await this.redis.get(this.key(userId, channelId));
    if (!raw) return null;

    const session = JSON.parse(raw);
    // Check expiration
    if (session.expiresAt && new Date(session.expiresAt) < new Date()) {
      await this.redis.del(this.key(userId, channelId));
      return null;
    }
    return {
      ...session,
      createdAt: new Date(session.createdAt),
      updatedAt: new Date(session.updatedAt),
      expiresAt: session.expiresAt ? new Date(session.expiresAt) : undefined,
    };
  }

  async set(userId: string, channelId: string, session: BotSession): Promise<void> {
    const key = this.key(userId, channelId);
    const ttl = session.expiresAt
      ? Math.ceil((session.expiresAt.getTime() - Date.now()) / 1000)
      : 86_400; // Default: 24 hours

    await this.redis.setex(key, ttl, JSON.stringify({
      ...session,
      updatedAt: new Date(),
    }));
  }

  async delete(userId: string, channelId: string): Promise<void> {
    await this.redis.del(this.key(userId, channelId));
  }

  async clear(userId: string): Promise<void> {
    const keys = await this.redis.keys(`${this.prefix}${userId}:*`);
    if (keys.length > 0) {
      await this.redis.del(...keys);
    }
  }
}
```

Usage:

```typescript
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);
const store = new RedisSessionStore(redis, 'mybot:session:');

builder.withSessionStore(store);
```

### Prisma Example

```typescript
import type { BotSessionStore, BotSession } from '@igniter-js/bot';
import { PrismaClient } from '@prisma/client';

class PrismaSessionStore implements BotSessionStore {
  constructor(private prisma: PrismaClient) {}

  async get(userId: string, channelId: string): Promise<BotSession | null> {
    const record = await this.prisma.botSession.findUnique({
      where: { userId_channelId: { userId, channelId } },
    });
    if (!record) return null;

    if (record.expiresAt && record.expiresAt < new Date()) {
      await this.prisma.botSession.delete({ where: { id: record.id } });
      return null;
    }

    return {
      userId: record.userId,
      channelId: record.channelId,
      data: record.data as Record<string, any>,
      createdAt: record.createdAt,
      updatedAt: record.updatedAt,
      expiresAt: record.expiresAt ?? undefined,
    };
  }

  async set(userId: string, channelId: string, session: BotSession): Promise<void> {
    await this.prisma.botSession.upsert({
      where: { userId_channelId: { userId, channelId } },
      create: {
        userId,
        channelId,
        data: session.data,
        expiresAt: session.expiresAt,
      },
      update: {
        data: session.data,
        expiresAt: session.expiresAt,
        updatedAt: new Date(),
      },
    });
  }

  async delete(userId: string, channelId: string): Promise<void> {
    await this.prisma.botSession.deleteMany({ where: { userId, channelId } });
  }

  async clear(userId: string): Promise<void> {
    await this.prisma.botSession.deleteMany({ where: { userId } });
  }
}
```

***

## Session Expiration

Set `expiresAt` on sessions for automatic cleanup:

```typescript
async handle(ctx) {
  await ctx.session.update({
    step: 'checkout',
    cart: items,
  });

  // Session expires in 30 minutes (for abandoned carts)
  ctx.session.expiresAt = new Date(Date.now() + 30 * 60 * 1000);
  await ctx.session.save();
}
```

The memory store includes a background cleanup interval. Custom stores should handle expiration in their `get()` method by checking `expiresAt`.

***

## Best Practices

* ✅ **Use `ctx.session.update()`** instead of modifying `ctx.session.data` directly — it auto-saves
* ✅ **Set expiration** for time-sensitive flows (checkout, verification codes)
* ✅ **Use a persistent store** (Redis, Prisma) in production — memory store loses data on restart
* ✅ **Keep session data small** — avoid storing large objects; use IDs and fetch from database
* ✅ **Clear sessions** when a flow completes (`ctx.session.delete()`)
* ❌ **Don't store sensitive data** in sessions without encryption
* ❌ **Don't use sessions as a database** — they're for temporary conversational state
* ❌ **Don't share session stores across unrelated bots** — use a prefix or separate Redis DB

***

## Next Steps

<Cards>
  <Card title="Framework Integration" description="Wire up your bot with Next.js, Express, and Fastify." href="/docs/bots/framework-integration" />

  <Card title="Real-World Examples" description="Complete production bot scenarios with code." href="/docs/bots/real-world" />

  <Card title="API Reference" description="Complete API documentation for all types and methods." href="/docs/bots/api-reference" />
</Cards>


---

# Troubleshooting

> Diagnose and fix common issues with @igniter-js/bot. Error codes, debugging techniques, webhook problems, and platform-specific troubleshooting.
URL: https://igniterjs.com/docs/bots/troubleshooting

## Troubleshooting

Common issues and solutions when building bots with `@igniter-js/bot`.

***

## Build Errors

### "At least one adapter is required"

**Symptom:** `.build()` throws: `At least one adapter is required.`

**Cause:** No adapters were added before calling `.build()`.

**Fix:**

```typescript
// Before
const bot = IgniterBot.create().build(); // ❌

// After
const bot = IgniterBot.create()
  .addAdapter('telegram', telegram({ token: '...' }))
  .build(); // ✅
```

***

### "Bot handle is required"

**Symptom:** `.build()` throws: `Bot handle is required.`

**Cause:** Neither a global handle (`withHandle()`) nor a per-adapter handle was configured.

**Fix:**

```typescript
// Option 1: Global handle
IgniterBot.create().withHandle('@mybot')

// Option 2: Per-adapter handles
IgniterBot.create().addAdapter('telegram', telegram({
  token: '...',
  handle: '@mybot',
}))
```

***

## Runtime Errors

### PROVIDER\_NOT\_FOUND

**Symptom:** `BotError: Provider 'xxx' not found`

**Cause:** An incoming request targets an adapter that wasn't registered, or the route's dynamic segment doesn't match.

**Fix:**

1. Check that the adapter key in your route matches the key used in `addAdapter()`:
   ```typescript
   // bot setup
   .addAdapter('telegram', tg)

   // route — must match
   app.all('/api/bot/telegram', ...) // 'telegram' must match
   ```
2. If using `nextRouteHandlerAdapter`, ensure the `[adapter]` segment matches:
   ```
   /api/bot/telegram/assistant_bot → adapter = 'telegram'
   ```

***

### CLIENT\_NOT\_PROVIDED

**Symptom:** `BotError: Telegram/WhatsApp/Discord client not provided`

**Cause:** The adapter's internal HTTP client initialization failed. This usually happens when configuration values are empty or invalid.

**Fix:**

1. Check that environment variables are set and accessible at runtime
2. Verify adapter configuration values are not empty strings:
   ```typescript
   // Debug: log config (never log tokens in production!)
   const tg = telegram({ token: process.env.TELEGRAM_TOKEN! });
   console.log('Token exists:', !!process.env.TELEGRAM_TOKEN);
   ```

***

### CONTENT\_TYPE\_NOT\_SUPPORTED

**Symptom:** `BotError: Poll content not supported by adapter 'whatsapp'`

**Cause:** Attempting to send a content type that the adapter's capabilities don't include.

**Fix:**

1. Check the [adapter capability table](/docs/bots/adapters#adapter-capability-comparison)
2. Use conditional logic:
   ```typescript
   async handle(ctx) {
     if (ctx.provider === 'whatsapp') {
       await ctx.reply('Polls are not available on WhatsApp. Reply with your choice: A, B, or C.');
     } else {
       await ctx.bot.send({
         provider: ctx.provider,
         channel: ctx.channel.id,
         content: { type: 'poll', question: '...', options: ['A', 'B', 'C'] },
       });
     }
   }
   ```

***

### INVALID\_COMMAND\_PARAMETERS

**Symptom:** Command handler receives unexpected arguments or resolves with an error.

**Cause:** The `args` Zod schema failed validation against user input.

**Fix:**

1. Check the Zod schema is correct:
   ```typescript
   args: z.object({
     query: z.string(), // Remember: strings without .optional() are required
   })
   ```
2. Test your schema manually:
   ```typescript
   import { z } from 'zod';
   const schema = z.object({ query: z.string().min(2) });
   schema.parse({ query: 'hi' }); // ✅ passes
   schema.parse({}); // ❌ throws ZodError
   ```
3. Provide clear error messages in `help`:
   ```typescript
   help: 'Use /search &lt;query&gt; [category: books|movies|music]',
   ```

***

## Webhook Issues

### Telegram: Webhook Not Receiving Updates

**Symptoms:** Bot is running but doesn't respond to messages.

**Checklist:**

1. **Verify webhook URL is publicly accessible:**
   ```bash
   curl https://your-domain.com/api/bot/telegram/assistant_bot
   ```
2. **Check webhook status via Telegram API:**
   ```bash
   curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"
   ```
   Look for `"ok": true` and `"url": "https://..."` and no `last_error_message`.
3. **Ensure HTTPS certificate is valid** — Telegram requires HTTPS.
4. **Delete and re-set the webhook manually:**
   ```bash
   curl "https://api.telegram.org/bot<TOKEN>/deleteWebhook"
   curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://..."
   ```
5. **Check the `dropPendingUpdates` setting** — if `false`, old updates may be processed first, making it seem like new messages don't work.

***

### Discord: 401 Unauthorized on Interactions

**Symptoms:** Discord returns "401 Unauthorized" for bot interactions.

**Checklist:**

1. **Verify `publicKey` is correct** — copy it from the Discord Developer Portal (General Information).
2. **Enable `X-Signature-Ed25519` header forwarding** in your proxy/reverse proxy configuration.
3. **Check that the raw request body is being forwarded** — some middleware (body parsers) may modify the body before the adapter reads it.

***

### WhatsApp: Messages Not Being Delivered

**Symptoms:** Bot receives webhooks but outbound messages don't arrive.

**Checklist:**

1. **Verify the phone number ID format:**
   ```typescript
   whatsapp({ phone: '1234567890' }) // Just the number, no + or spaces
   ```
2. **Check the message template status** — some message types require pre-approved templates.
3. **Verify the recipient has opted in** — WhatsApp requires users to message first.
4. **Check rate limits** — WhatsApp Cloud API has strict rate limits (80 messages/second for business accounts).

***

## Session Issues

### Sessions Not Persisting

**Symptoms:** `ctx.session.data` is always empty or reset to defaults.

**Checklist:**

1. **Use `ctx.session.update()` not direct mutation:**
   ```typescript
   // ✅ Works
   await ctx.session.update({ step: 'checkout' });

   // ❌ May not persist
   ctx.session.data.step = 'checkout';
   ```
2. **Check that the session store is configured:**
   ```typescript
   // Must be set before .build()
   builder.withSessionStore(memoryStore())
   ```
3. **If using memory store in production:** It doesn't persist across restarts. Use Redis or Prisma.

***

### Redis Sessions Timeout

**Symptoms:** Sessions expire too quickly in Redis.

**Checklist:**

1. **Check the TTL in your Redis store implementation** — the default is 24 hours if `expiresAt` is not set.
2. **Verify Redis connection is stable** — check for connection drops or timeouts.
3. **Check for Redis maxmemory eviction** — if `maxmemory-policy` is set to `allkeys-lru`, sessions may be evicted.

***

## Rate Limiting Issues

### Users Being Rate Limited Too Quickly

**Symptoms:** Legitimate users hit rate limits within seconds.

**Checklist:**

1. **Check your `windowMs` and `maxRequests`:**
   ```typescript
   rateLimitMiddleware({
     maxRequests: 10,
     windowMs: 60_000, // 1 minute — not 1 second!
   })
   ```
2. **Use the correct key generator:**
   ```typescript
   // Per-user (default)
   keyGenerator: (ctx) => `${ctx.provider}:${ctx.message.author.id}`

   // Per-user-per-command (more granular)
   keyGenerator: (ctx) => {
     const cmd = ctx.message.content?.type === 'command' ? ctx.message.content.command : 'message';
     return `${ctx.provider}:${ctx.message.author.id}:${cmd}`;
   }
   ```
3. **Memory store is per-process** — if you have multiple instances, each has its own counter. Use Redis for shared state.

***

## TypeScript Issues

### "Property does not exist on type BotContext"

**Symptom:** TypeScript error when accessing enriched context properties.

**Fix:** Middleware enrichment flows through the builder's generic types:

```typescript
// The builder tracks middleware return types
const bot = IgniterBot.create()
  .addMiddleware(async (ctx, next) => {
    await next();
    return { user: { id: '123' } }; // returned
  })
  .addCommand('profile', {
    async handle(ctx) {
      ctx.user.id; // ✅ TypeScript knows about this
    },
  })
  .build();
```

If you're accessing enriched context in a separate file, cast as needed:

```typescript
type EnrichedContext = BotContext & { user: { id: string } };

async handle(ctx) {
  const enriched = ctx as EnrichedContext;
  console.log(enriched.user.id);
}
```

***

## Debugging Tips

### Enable Verbose Logging

```typescript
import { loggingPresets } from '@igniter-js/bot';

builder.addMiddleware(loggingPresets.debug());
```

This logs every message, command, error, and metric with full detail.

### Check Adapter Status

```typescript
console.log('Registered adapters:', Object.keys(bot.getAdapters()));
console.log('Telegram adapter:', bot.getAdapter('telegram'));
```

### Test Webhook Manually

```bash
# Simulate a Telegram message (use actual token and chat ID)
curl -X POST "https://your-domain.com/api/bot/telegram/assistant_bot" \
  -H "Content-Type: application/json" \
  -d '{"update_id": 1, "message": {"message_id": 1, "from": {"id": 123, "is_bot": false, "first_name": "Test"}, "chat": {"id": 123, "type": "private"}, "date": 1234567890, "text": "/start"}}'
```

### Inspect Session Data

```typescript
builder.addMiddleware(async (ctx, next) => {
  console.log('Session data:', ctx.session.data);
  await next();
});
```

***

## Still Stuck?

1. **Check the [API Reference](/docs/bots/api-reference)** for exact method signatures
2. **Review [Best Practices](/docs/bots/best-practices)** for common patterns
3. **Read the adapter source code** at `packages/bot/src/adapters/` — it's well-documented
4. **Enable debug logging** with `loggingPresets.debug()` for full request tracing

***

## Next Steps

<Cards>
  <Card title="Real-World Examples" description="Complete production bot scenarios with code." href="/docs/bots/real-world" />

  <Card title="API Reference" description="Complete API documentation for all methods and types." href="/docs/bots/api-reference" />

  <Card title="Best Practices" description="Production patterns, security, and architecture guides." href="/docs/bots/best-practices" />
</Cards>


---

# API Reference

> Complete API reference for @igniter-js/caller — all classes, methods, types, and configuration options.
URL: https://igniterjs.com/docs/caller/api-reference

## IgniterCaller

The main entrypoint for creating API client instances.

```typescript
import { IgniterCaller } from '@igniter-js/caller';
```

### `IgniterCaller.create()`

Creates a new `IgniterCallerBuilder` instance with an empty configuration.

```typescript
const api = IgniterCaller.create()
  .withBaseUrl('https://api.example.com')
  .build();
```

***

## IgniterCallerBuilder

Immutable builder for configuring the API client. Every `with*` method returns a new builder instance.

<TypeTable
  type={{
create: {
  type: '() => IgniterCallerBuilder<{}>',
  description: 'Static factory. Creates a new builder with empty state.',
},
withBaseUrl: {
  type: '(baseURL: string) => this',
  description: 'Sets the base URL prefixed to all requests.',
},
withHeaders: {
  type: '(headers: Record<string, string>) => this',
  description: 'Sets default headers merged into every request.',
},
withCookies: {
  type: '(cookies: Record<string, string>) => this',
  description: 'Sets default cookies (serialized into the Cookie header).',
},
withLogger: {
  type: '(logger: IgniterLogger) => this',
  description: 'Attaches a logger instance for request lifecycle logging.',
},
withTelemetry: {
  type: '(telemetry: IgniterTelemetryManager) => this',
  description: 'Attaches a telemetry manager for observability events.',
},
withSchemas: {
  type: '(schemas: SchemaMap | SchemaBuildResult, validation?: SchemaValidationOptions) => this',
  description: 'Configures schema-based type inference and optional runtime validation. Accepts a raw schema map or a build result from IgniterCallerSchema.',
},
withRequestInterceptor: {
  type: '(interceptor: (config: RequestOptions) => RequestOptions | Promise<RequestOptions>) => this',
  description: 'Adds a request interceptor that can modify request options before execution.',
},
withResponseInterceptor: {
  type: '(interceptor: (response: ApiResponse) => ApiResponse | Promise<ApiResponse>) => this',
  description: 'Adds a response interceptor that can transform responses after execution.',
},
withStore: {
  type: '(store: StoreAdapter, options?: StoreOptions) => this',
  description: 'Configures a persistent store adapter for caching (e.g., Redis).',
},
withMock: {
  type: '(config: { enabled: boolean; delay?: number; mock: MockManager }) => this',
  description: 'Enables mock mode. Requests matching mock handlers skip real network calls.',
},
build: {
  type: '() => IgniterCallerManager<TSchemas>',
  description: 'Finalizes configuration. Logs initialization details and returns the manager instance.',
},
}}
/>

***

## IgniterCallerManager

The runtime engine returned by `.build()`. Used to create and execute HTTP requests.

### Instance Methods

All HTTP method helpers accept an optional URL. When schemas are configured, providing a URL enables full type inference.

<TypeTable
  type={{
get: {
  type: '(url?: string) => RequestBuilder<T>',
  description: 'Creates a GET request builder. Supports path params via :param syntax.',
},
post: {
  type: '(url?: string) => RequestBuilder<T>',
  description: 'Creates a POST request builder.',
},
put: {
  type: '(url?: string) => RequestBuilder<T>',
  description: 'Creates a PUT request builder (idempotent, replaces entire resource).',
},
patch: {
  type: '(url?: string) => RequestBuilder<T>',
  description: 'Creates a PATCH request builder (partial update).',
},
delete: {
  type: '(url?: string) => RequestBuilder<T>',
  description: 'Creates a DELETE request builder.',
},
head: {
  type: '(url?: string) => RequestBuilder<T>',
  description: 'Creates a HEAD request builder (headers only, no body).',
},
request: {
  type: '(options: DirectRequestOptions) => Promise<ApiResponse<T>>',
  description: 'Executes a request directly using an options object. Convenience method for dynamic or programmatic requests.',
},
}}
/>

### Static Methods

<TypeTable
  type={{
on: {
  type: '(pattern: string | RegExp, callback: (result: ApiResponse, context: { url, method, timestamp }) => void) => () => void',
  description: 'Registers a global event listener for matching responses. Returns an unsubscribe function. Pattern can be a string or RegExp.',
},
batch: {
  type: '(requests: Promise<ApiResponse>[]) => Promise<ApiResponse[]>',
  description: 'Executes multiple requests in parallel using Promise.all semantics. Results preserve the input order.',
},
}}
/>

***

## IgniterCallerRequestBuilder

Fluent per-request API. Returned by `api.get()`, `api.post()`, etc. All methods return `this` for chaining.

### Request Configuration

<TypeTable
  type={{
url: {
  type: '(url: string) => this',
  description: 'Sets the request URL or path (relative to base URL).',
},
body: {
  type: '(data: unknown) => this',
  description: 'Sets the request body. Objects/arrays are auto-serialized to JSON. For GET/HEAD, body is converted to query params.',
},
params: {
  type: '(params: Record<string, string | number | boolean>) => this',
  description: 'Sets URL path parameters (replacing :param segments) and query string parameters. Extra params become query string.',
},
headers: {
  type: '(headers: Record<string, string>) => this',
  description: 'Merges additional headers. Overrides defaults with the same name.',
},
timeout: {
  type: '(ms: number) => this',
  description: 'Sets request timeout in milliseconds. Default: 30000 (30s). Triggers AbortError on expiry.',
},
}}
/>

### Resilience

<TypeTable
  type={{
retry: {
  type: '(maxAttempts: number, options?: { backoff?: "linear" | "exponential"; baseDelay?: number; retryOnStatus?: number[] }) => this',
  description: 'Configures automatic retry on failure. maxAttempts is the number of retry attempts (total attempts = 1 + maxAttempts). Default backoff: linear. Default retryOnStatus: [408, 429, 500, 502, 503, 504].',
},
fallback: {
  type: '(fn: () => T) => this',
  description: 'Provides a fallback factory function. Called if all retry attempts fail. The result is returned as data, with no error.',
},
cache: {
  type: '(strategy: RequestCache, key?: string) => this',
  description: 'Sets the fetch RequestCache strategy (e.g., "default", "no-store", "reload", "force-cache"). Optional key for manual cache management.',
},
stale: {
  type: '(milliseconds: number) => this',
  description: 'Enables response caching for the specified duration. Subsequent requests within the stale time return cached data instead of making a network call.',
},
}}
/>

### Response Typing

<TypeTable
  type={{
responseType: {
  type: '<T>(schema?: ZodSchema<T> | StandardSchemaV1) => RequestBuilder<T>',
  description: 'Sets the expected response type for TypeScript inference. If a Zod/StandardSchema is passed, the response is validated at runtime (only for JSON/XML/CSV content types). If no schema is passed, it provides type inference only.',
},
}}
/>

### Execution

<TypeTable
  type={{
execute: {
  type: '() => Promise<ApiResponse<T>>',
  description: 'Executes the request. Runs through the full pipeline: cache check → interceptors → validation → fetch (with retry) → parsing → validation → interceptors → cache store → fallback.',
},
}}
/>

***

## IgniterCallerSchema

Path-first schema builder for defining type-safe API contracts with Zod (or any StandardSchemaV1 library).

<TypeTable
  type={{
create: {
  type: '() => IgniterCallerSchema<{}, {}>',
  description: 'Creates a new empty schema builder.',
},
schema: {
  type: '(key: string, schema: StandardSchemaV1, options?: { internal?: boolean }) => this',
  description: 'Registers a reusable schema in the registry. Can be referenced by key in path definitions via path.ref(key).',
},
path: {
  type: '(path: string, builder: (pathBuilder: SchemaPathBuilder) => SchemaPathBuilder) => this',
  description: 'Defines a path with its HTTP methods. The builder callback receives a SchemaPathBuilder to define GET, POST, etc. Path must start with /.',
},
build: {
  type: '() => SchemaBuildResult<TSchemas, TRegistry>',
  description: 'Builds the schema map. Returns an object with $Infer and get helpers for type extraction.',
},
}}
/>

### SchemaPathBuilder

Defines HTTP methods for a single path:

| Method           | Signature                                                                | Description                                      |
| ---------------- | ------------------------------------------------------------------------ | ------------------------------------------------ |
| `get(config)`    | `(config: { request?, responses }) => this`                              | Defines GET endpoint                             |
| `post(config)`   | `(config: { request?, responses }) => this`                              | Defines POST endpoint                            |
| `put(config)`    | `(config: { request?, responses }) => this`                              | Defines PUT endpoint                             |
| `patch(config)`  | `(config: { request?, responses }) => this`                              | Defines PATCH endpoint                           |
| `delete(config)` | `(config: { request?, responses }) => this`                              | Defines DELETE endpoint                          |
| `head(config)`   | `(config: { request?, responses }) => this`                              | Defines HEAD endpoint                            |
| `ref(key)`       | `(key: string) => { schema, array(), nullable(), optional(), record() }` | References a registered schema with Zod wrappers |
| `build()`        | `() => TMethods`                                                         | Returns the accumulated method map               |

***

## IgniterCallerMock

Builder for creating typed mock registries for testing.

<TypeTable
  type={{
create: {
  type: '() => IgniterCallerMockBuilder<{}>',
  description: 'Creates a new mock builder.',
},
withSchemas: {
  type: '(schemas: SchemaMap | SchemaBuildResult) => this',
  description: 'Associates schemas for typed mock definitions. Mocks validate against schema types.',
},
mock: {
  type: '(path: string, handlers: MockPathDefinition) => this',
  description: 'Registers mock handlers for a path. Handlers can be static responses or dynamic functions receiving request context.',
},
build: {
  type: '() => IgniterCallerMockManager<TSchemas>',
  description: 'Builds the mock manager instance.',
},
}}
/>

### Mock Handler Shapes

Static response:

```typescript
{ response: data; status?: number; headers?: Record<string, string>; delayMs?: number }
```

Dynamic handler:

```typescript
(request: { method; path; url; headers; query; params; body?; ... }) => MockResponse
```

***

## MockCallerStoreAdapter

In-memory store adapter for testing. Implements the `IgniterCallerStoreAdapter` interface.

```typescript
import { MockCallerStoreAdapter } from '@igniter-js/caller/adapters';
```

<TypeTable
  type={{
create: {
  type: '() => MockCallerStoreAdapter',
  description: 'Creates a new mock adapter with call tracking.',
},
client: {
  type: 'Map<string, unknown>',
  description: 'Underlying in-memory store.',
},
calls: {
  type: '{ get: number; set: number; delete: number; has: number }',
  description: 'Call counters for assertions.',
},
history: {
  type: '{ get: string[]; set: Array<{ key, value, options? }>; delete: string[]; has: string[] }',
  description: 'Operation history for detailed assertions.',
},
clear: {
  type: '() => void',
  description: 'Clears all tracked state (store, calls, history).',
},
}}
/>

***

## Types

### `IgniterCallerApiResponse<T>`

The standardized response envelope returned by all requests.

<TypeTable
  type={{
data: {
  type: 'T | undefined',
  description: 'The parsed response data. Undefined if the request failed.',
},
error: {
  type: 'IgniterError | undefined',
  description: 'The error object if the request failed. Undefined on success.',
},
status: {
  type: 'number | undefined',
  description: 'The HTTP status code of the response.',
},
headers: {
  type: 'Headers | undefined',
  description: 'The response headers object.',
},
}}
/>

### `IgniterCallerError`

Custom error class extending `IgniterError` for all Caller failures.

<TypeTable
  type={{
code: {
  type: 'IgniterCallerErrorCode',
  description: 'Stable error code (e.g., IGNITER_CALLER_TIMEOUT, IGNITER_CALLER_HTTP_ERROR).',
},
message: {
  type: 'string',
  description: 'Human-readable error message.',
},
operation: {
  type: 'IgniterCallerOperation',
  description: 'The operation that failed (execute, download, buildSchema, etc.).',
},
statusText: {
  type: 'string | undefined',
  description: 'HTTP status text from the response.',
},
cause: {
  type: 'Error | undefined',
  description: 'The original error that caused this failure.',
},
is: {
  type: '(error: unknown) => boolean',
  description: 'Static type guard. Returns true if the value is an IgniterCallerError.',
},
}}
/>

### Error Codes

| Code                                        | Description                             |
| ------------------------------------------- | --------------------------------------- |
| `IGNITER_CALLER_HTTP_ERROR`                 | HTTP response status ≥ 400              |
| `IGNITER_CALLER_MOCK_HTTP_ERROR`            | Mock handler returned an error response |
| `IGNITER_CALLER_TIMEOUT`                    | Request exceeded the configured timeout |
| `IGNITER_CALLER_REQUEST_VALIDATION_FAILED`  | Request body failed schema validation   |
| `IGNITER_CALLER_RESPONSE_VALIDATION_FAILED` | Response body failed schema validation  |
| `IGNITER_CALLER_SCHEMA_DUPLICATE`           | Duplicate schema path or method         |
| `IGNITER_CALLER_SCHEMA_INVALID`             | Invalid schema configuration            |
| `IGNITER_CALLER_UNKNOWN_ERROR`              | Unexpected catch-all error              |

### `IgniterCallerStoreAdapter`

Interface for implementing persistent cache stores.

<TypeTable
  type={{
client: {
  type: 'T',
  description: 'The underlying client instance (e.g., Redis client).',
},
get: {
  type: '(key: string) => Promise<T | null>',
  description: 'Retrieves a cached value by key.',
},
set: {
  type: '(key: string, value: any, options?: { ttl?: number }) => Promise<void>',
  description: 'Stores a cached value with optional TTL.',
},
delete: {
  type: '(key: string) => Promise<void>',
  description: 'Removes a cached value.',
},
has: {
  type: '(key: string) => Promise<boolean>',
  description: 'Checks if a key exists in the store.',
},
}}
/>

### `IgniterCallerRetryOptions`

<TypeTable
  type={{
maxAttempts: {
  type: 'number',
  description: 'Maximum number of retry attempts (default: 1 retry = 2 total attempts).',
},
backoff: {
  type: '"linear" | "exponential"',
  description: 'Delay strategy. Linear: baseDelay × attempt. Exponential: baseDelay × 2^attempt.',
},
baseDelay: {
  type: 'number',
  description: 'Initial delay in milliseconds (default: 1000).',
},
retryOnStatus: {
  type: 'number[]',
  description: 'HTTP status codes that trigger retry (default: [408, 429, 500, 502, 503, 504]).',
},
}}
/>

### `IgniterCallerStoreOptions`

<TypeTable
  type={{
ttl: {
  type: 'number',
  description: 'Default TTL in seconds for cached entries (default: 3600).',
},
keyPrefix: {
  type: 'string',
  description: 'Prefix for all cache keys (default: igniter:caller:).',
},
fallbackToFetch: {
  type: 'boolean',
  description: 'Fall back to fetch cache when store is unavailable (default: true).',
},
}}
/>

***

## Subpath Exports

| Import Path                    | Purpose                                                                   |
| ------------------------------ | ------------------------------------------------------------------------- |
| `@igniter-js/caller`           | Core client: IgniterCaller, IgniterCallerSchema, IgniterCallerMock, types |
| `@igniter-js/caller/client`    | React integration: IgniterCallerProvider, useIgniterCaller, hooks         |
| `@igniter-js/caller/telemetry` | Telemetry events: IgniterCallerTelemetryEvents                            |
| `@igniter-js/caller/adapters`  | Store adapters: MockCallerStoreAdapter                                    |


---

# CLI Integration

> Automate your API client setup with the Igniter CLI.
URL: https://igniterjs.com/docs/caller/cli

The Igniter CLI allows you to generate a fully typed Caller and its corresponding Zod schemas directly from an OpenAPI 3 specification. This is the fastest way to integrate third-party APIs or sync with your own backend.

## Generation Command

Use the `generate caller` command:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli generate caller --name facebook --url https://api.facebook.com/openapi.json
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm igniter generate caller --name facebook --url https://api.facebook.com/openapi.json
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn igniter generate caller --name facebook --url https://api.facebook.com/openapi.json
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli generate caller --name facebook --url https://api.facebook.com/openapi.json
    ```
  </Tab>
</Tabs>

### Command Options

| Option     | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `--name`   | Prefix for the generated variables and file naming.            |
| `--url`    | Remote URL of the OpenAPI JSON/YAML.                           |
| `--path`   | Local file path to the OpenAPI spec.                           |
| `--output` | Override output directory (default: `src/callers/<hostname>`). |

## Generated Assets

The command generates two main files in your project:

1. **`schema.ts`**: Contains all Zod schemas derived from `components/schemas` and a path-first `IgniterCallerSchema` builder.
2. **`index.ts`**: Exports a pre-configured `IgniterCaller` instance.

### Using the Generated Caller

```ts
import { facebookCaller } from '@/callers/facebook'
import type { FacebookCallerSchemas } from '@/callers/facebook/schema'

// Making a request (URL is typed!)
const result = await facebookCaller.get('/me').execute()

// Type inference for responses
type MeResponse = ReturnType<
  typeof FacebookCallerSchemas.$Infer.Response<'/me', 'GET', 200>
>
```

## Why use CLI Generation?

* **Zero Manual Typing**: Keep your TS types perfectly in sync with the API documentation.
* **Runtime Safety**: Automatic validation ensures the data you receive matches the code you wrote.
* **Speed**: Go from an URL to a production-ready client in seconds.

***

## Manual Schemas

If you don't have an OpenAPI spec, you can still define [Manual Schemas](/docs/caller/schemas) using the `IgniterCallerSchema` builder.


---

# Comparison

> How Caller compares to Axios, ky, ofetch, and native fetch. Understand the trade-offs and choose the right HTTP client for your project.
URL: https://igniterjs.com/docs/caller/comparison

## Overview

The JavaScript ecosystem has many excellent HTTP clients. This page provides an honest comparison between Caller and popular alternatives, helping you understand when Caller is the right choice and when you might prefer something else.

We believe in picking the right tool for the job. Caller excels at type-safe, schema-validated API consumption in TypeScript projects—but it's not always the best choice for every scenario.

***

## Quick Comparison

| Feature               | Caller           | Axios     | ky         | ofetch     | fetch  |
| --------------------- | ---------------- | --------- | ---------- | ---------- | ------ |
| **Type Safety**       | ✅ Full inference | ⚠️ Manual | ⚠️ Manual  | ⚠️ Manual  | ❌ None |
| **Schema Validation** | ✅ Built-in       | ❌         | ❌          | ❌          | ❌      |
| **Fluent API**        | ✅                | ❌         | ✅          | ⚠️ Partial | ❌      |
| **Retries**           | ✅ Built-in       | ❌ Plugin  | ✅ Built-in | ✅ Built-in | ❌      |
| **Caching**           | ✅ Built-in       | ❌         | ❌          | ❌          | ❌      |
| **React Hooks**       | ✅ Built-in       | ❌         | ❌          | ❌          | ❌      |
| **Interceptors**      | ✅                | ✅         | ✅          | ✅          | ❌      |
| **Bundle Size**       | \~8kb            | \~13kb    | \~4kb      | \~5kb      | 0kb    |
| **Node.js Support**   | ✅                | ✅         | ✅          | ✅          | ✅ 18+  |
| **Browser Support**   | Modern           | All       | Modern     | Modern     | Modern |

***

## Detailed Comparisons

<Accordions>
  <Accordion title="Caller vs Axios">
    **Axios** is the most popular HTTP client in the JavaScript ecosystem with excellent browser compatibility and a mature ecosystem.

    ### When to choose Axios

    * You need to support older browsers (IE11)
    * Your team is already familiar with Axios
    * You need upload progress events
    * You're working in a pure JavaScript project

    ### When to choose Caller

    * You want automatic type inference from schemas
    * You need built-in caching and retries
    * You're building with React and want hooks
    * You value compile-time API contract validation

    ### Code Comparison

    ```typescript title="Axios"
    import axios from 'axios';

    interface User {
      id: string;
      name: string;
    }

    // Manual type annotation required
    const response = await axios.get<User>('/users/123');
    const user = response.data; // Type: User (but not validated)
    ```

    ```typescript title="Caller"
    import { api } from './lib/api';

    // Type inferred from schema, validated at runtime
    const { data } = await api.get('/users/:id')
      .params({ id: '123' })
      .execute();
    // data is typed AND validated
    ```

    **Key Difference:** Axios requires you to manually define and maintain TypeScript interfaces. Caller infers types from your schema definitions and validates responses at runtime.
  </Accordion>

  <Accordion title="Caller vs ky">
    **ky** is a lightweight HTTP client with a clean API, built by the creator of got. It's essentially a modern wrapper around fetch.

    ### When to choose ky

    * You want the smallest possible bundle size
    * You prefer a minimal API surface
    * You don't need schema validation
    * You're doing simple HTTP requests without complex flows

    ### When to choose Caller

    * You want type-safe API contracts
    * You need schema validation out of the box
    * You want React integration
    * You're building an Igniter.js application

    ### Code Comparison

    ```typescript title="ky"
    import ky from 'ky';

    const user = await ky.get('https://api.example.com/users/123').json();
    // Type: unknown - requires manual casting
    ```

    ```typescript title="Caller"
    const { data } = await api.get('/users/:id')
      .params({ id: '123' })
      .execute();
    // Type: { id: string; name: string } - from schema
    ```

    **Key Difference:** ky focuses on being a thin, elegant wrapper around fetch. Caller adds a comprehensive type system and validation layer on top.
  </Accordion>

  <Accordion title="Caller vs ofetch">
    **ofetch** (from UnJS/Nuxt team) is a modern fetch wrapper with automatic JSON parsing, retries, and good defaults.

    ### When to choose ofetch

    * You're building a Nuxt application
    * You want a simple, batteries-included fetch wrapper
    * You don't need schema-level type safety
    * You want universal (Node/Browser) support out of the box

    ### When to choose Caller

    * You want compile-time type checking of API contracts
    * You need built-in caching with invalidation
    * You're building with React
    * You want to generate clients from OpenAPI specs

    ### Code Comparison

    ```typescript title="ofetch"
    import { ofetch } from 'ofetch';

    const user = await ofetch('/users/123', {
      retry: 3,
      retryDelay: 1000,
    });
    // Type: unknown
    ```

    ```typescript title="Caller"
    const { data } = await api.get('/users/:id')
      .params({ id: '123' })
      .retry({ attempts: 3, baseDelay: 1000 })
      .execute();
    // Type: User (from schema)
    ```

    **Key Difference:** ofetch is excellent for quick, type-agnostic requests. Caller shines when you want your entire API surface typed and validated.
  </Accordion>

  <Accordion title="Caller vs Native fetch">
    **fetch** is the standard API built into modern browsers and Node.js 18+. No dependencies needed.

    ### When to choose fetch

    * You have very simple needs (one or two API calls)
    * You want zero dependencies
    * You're writing a library that can't have external deps
    * You're comfortable handling all edge cases manually

    ### When to choose Caller

    * You're building an application with many API calls
    * You want consistent error handling
    * You need retries, caching, or timeouts
    * You value developer experience and type safety

    ### Code Comparison

    ```typescript title="Native fetch"
    interface User {
      id: string;
      name: string;
    }

    const response = await fetch('https://api.example.com/users/123');

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    const user = await response.json() as User;
    // Type: User (but cast, not validated)
    ```

    ```typescript title="Caller"
    const { data, error } = await api.get('/users/:id')
      .params({ id: '123' })
      .execute();

    if (error) {
      // Structured error with code, message, status
      console.error(error.code, error.message);
    }
    // data is typed and validated
    ```

    **Key Difference:** fetch requires significant boilerplate for production use (error handling, retries, timeouts, type safety). Caller provides all of this out of the box.
  </Accordion>
</Accordions>

***

## Feature Deep Dive

### Type Safety

The biggest differentiator between Caller and alternatives is the type system. Most HTTP clients require you to manually define interfaces and hope they match your API:

```typescript title="Traditional Approach"
// You define this manually
interface User {
  id: string;
  name: string;
  email: string;
}

// API changes "email" to "emailAddress"
// TypeScript doesn't know - runtime error!
const user = await axios.get<User>('/users/123');
console.log(user.data.email); // undefined at runtime
```

With Caller, your schema is the source of truth:

```typescript title="Caller Approach"
// Schema is the source of truth
const schemas = IgniterCallerSchema.create()
  .path('/users/:id', (path) =>
    path.get({
      responses: {
        200: z.object({
          id: z.string(),
          name: z.string(),
          emailAddress: z.string(), // API changed this
        }),
      },
    })
  )
  .build();

const { data } = await api.get('/users/:id').execute();
console.log(data.emailAddress); // TypeScript knows the correct field
```

### React Integration

Caller provides first-class React hooks, while other libraries require external wrappers like TanStack Query:

```tsx title="Caller React Hooks"
import { useCaller } from '@igniter-js/caller/client';

function UserProfile({ id }: { id: string }) {
  const api = useCaller('main');
  
  const { data, isLoading } = api.get('/users/:id')
    .params({ id })
    .useQuery({ staleTime: 10_000 });
  
  return <div>{data?.name}</div>;
}
```

```tsx title="Axios + TanStack Query"
import { useQuery } from '@tanstack/react-query';
import axios from 'axios';

function UserProfile({ id }: { id: string }) {
  const { data, isLoading } = useQuery({
    queryKey: ['user', id],
    queryFn: () => axios.get(`/users/${id}`).then(r => r.data),
  });
  
  return <div>{data?.name}</div>;
}
```

***

## Migration Guides

<Cards>
  <Card title="From Axios" description="Step-by-step guide to migrate from Axios to Caller" href="/docs/caller/migration/axios" />

  <Card title="From fetch" description="How to upgrade from native fetch to Caller" href="/docs/caller/migration/fetch" />
</Cards>

***

## Summary

| Scenario                                    | Recommendation      |
| ------------------------------------------- | ------------------- |
| New TypeScript project with APIs            | **Caller**          |
| Existing Axios codebase, no time to migrate | **Axios**           |
| Ultra-minimal bundle, simple needs          | **ky** or **fetch** |
| Nuxt.js application                         | **ofetch**          |
| IE11 support required                       | **Axios**           |
| Type-safe, validated API layer              | **Caller**          |

Choose Caller when type safety, developer experience, and production-readiness matter. Choose alternatives when simplicity or specific compatibility requirements take priority.

***

## Next Steps

<Cards>
  <Card title="Installation" description="Get started with Caller in your project" href="/docs/caller/installation" />

  <Card title="Request Builder" description="Learn the fluent API in depth" href="/docs/caller/builder" />
</Cards>


---

# Introduction

> A type-safe HTTP client for Igniter.js with automatic schema validation, caching, retries, and React integration. Built on native fetch.
URL: https://igniterjs.com/docs/caller

## The Missing Piece

Every modern application needs to talk to APIs. Whether you're fetching user data, sending form submissions, or syncing with third-party services, HTTP requests are everywhere. But making HTTP requests in TypeScript has always been frustrating:

* **No type safety** — responses are `any` by default, forcing you to cast or define interfaces manually
* **Boilerplate everywhere** — error handling, retries, and caching require custom code for each request
* **Client/server disconnect** — types defined on the server don't automatically flow to the client
* **Testing is painful** — mocking fetch or axios requires complex setup

**Caller** solves all of these problems with a simple, fluent API.

```typescript
// Define your API once
const api = IgniterCaller.create()
  .withBaseUrl('https://api.example.com')
  .withSchemas(myApiSchemas)
  .build();

// Every request is fully typed
const { data, error } = await api.get('/users/:id')
  .params({ id: '123' })
  .execute();

// data is automatically typed as User — no manual interfaces!
console.log(data?.name);
```

<Callout type="success" title="Zero Configuration">
  Caller works out of the box with no setup. `IgniterCaller.create().build()` is all you need to start making requests.
</Callout>

***

## Why Caller?

<Accordions>
  <Accordion title="End-to-End Type Safety">
    Define your API schema once and get automatic TypeScript inference everywhere. When your server response changes, TypeScript catches breaking changes instantly.

    ```typescript
    const schemas = IgniterCallerSchema.create()
      .path('/users/:id', (path) =>
        path.get({
          responses: {
            200: z.object({ id: z.string(), name: z.string() }),
            404: z.object({ message: z.string() }),
          },
        })
      )
      .build();

    // TypeScript knows exact response types
    const { data } = await api.get('/users/:id').params({ id: '1' }).execute();
    //    ^? { id: string; name: string } | undefined
    ```

    No more `as User` casts or manually syncing interfaces between client and server.
  </Accordion>

  <Accordion title="Fluent Builder API">
    Chain methods naturally to configure your requests. Every method returns the builder, enabling powerful composition.

    ```typescript
    const result = await api.post('/users')
      .body({ name: 'John', email: 'john@example.com' })
      .headers({ 'X-Request-ID': crypto.randomUUID() })
      .timeout(5000)
      .retry(3, { backoff: 'exponential' })
      .execute();
    ```
  </Accordion>

  <Accordion title="Built-in Resilience">
    Production applications need retry logic, timeouts, and fallbacks. Caller provides these out of the box.

    ```typescript
    const { data } = await api.get('/external-service')
      .retry(3, { backoff: 'exponential', baseDelay: 500 })
      .timeout(10_000)
      .fallback(() => ({ cached: true, stale: true }))
      .execute();
    ```

    No more writing custom retry wrappers or handling transient failures manually.
  </Accordion>

  <Accordion title="Intelligent Caching">
    Cache responses automatically with configurable stale times. Invalidate programmatically when data changes.

    ```typescript
    // Cache for 5 minutes
    const users = await api.get('/users')
      .stale(300_000)
      .execute();

    // Make a mutation...
    await api.post('/users').body(newUser).execute();
    // Next GET /users call will fetch fresh data after stale time expires
    ```
  </Accordion>

  <Accordion title="React Integration">
    First-class React hooks for data fetching with automatic loading states, refetching, and cache invalidation.

    ```tsx
    function UserProfile({ id }: { id: string }) {
      const main = useCaller('main');

      const { data, isLoading, error } = main.get('/users/:id')
        .params({ id })
        .useQuery({ staleTime: 30_000 });

      if (isLoading) return <Skeleton />;
      if (error) return <ErrorMessage error={error} />;

      return <h1>{data?.name}</h1>;
    }
    ```
  </Accordion>
</Accordions>

***

## Architecture

Caller follows a builder pattern similar to other Igniter.js packages:

```
IgniterCaller.create()
  → .withBaseUrl() / .withSchemas() / .withInterceptors()
  → .build()
  → IgniterCallerManager
  → .get() / .post() / .put() / .patch() / .delete()
  → IgniterCallerRequestBuilder
  → .params() / .body() / .retry() / .stale()
  → .execute()
  → Type-Safe Response
```

Key components:

| Component                       | Purpose                                      |
| ------------------------------- | -------------------------------------------- |
| **IgniterCaller**               | Entry point — creates the builder            |
| **IgniterCallerBuilder**        | Immutable configuration chain                |
| **IgniterCallerManager**        | Runtime engine that executes requests        |
| **IgniterCallerRequestBuilder** | Fluent per-request API                       |
| **IgniterCallerSchema**         | Type-safe schema definitions with validation |
| **IgniterCallerMock**           | Typed mock registry for testing              |

***

## Quick Start

<Steps>
  <Step>
    ### Install the Package

    <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
      <Tab value="npm">
        ```bash
        npm install @igniter-js/caller
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @igniter-js/caller
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @igniter-js/caller
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @igniter-js/caller
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Create Your Client

    ```typescript title="lib/api.ts"
    import { IgniterCaller } from '@igniter-js/caller';

    export const api = IgniterCaller.create()
      .withBaseUrl(process.env.API_URL || 'http://localhost:3000')
      .build();
    ```
  </Step>

  <Step>
    ### Make Your First Request

    ```typescript
    import { api } from './lib/api';

    async function fetchUsers() {
      const { data, error } = await api.get('/users').execute();

      if (error) {
        console.error('Failed to fetch users:', error.message);
        return [];
      }

      return data;
    }
    ```
  </Step>
</Steps>

That's it! You now have a working HTTP client. Continue to [Quick Start](/docs/caller/quick-start) for a guided tutorial, or jump to [Core Concepts](/docs/caller/builder) to learn about the builder pattern.

***

## When to Use Caller

Caller is ideal for:

* ✅ **Igniter.js applications** — seamless integration with the framework
* ✅ **Type-safe API clients** — compile-time validation of your API contracts
* ✅ **React/Next.js projects** — built-in hooks and SSR support
* ✅ **Microservices communication** — retries, caching, and observability
* ✅ **OpenAPI consumers** — generate clients from specs with the CLI

Consider alternatives if:

* ❌ You need browser support for IE11 (Caller uses native fetch)
* ❌ You're building a simple script with one-off requests (use `fetch` directly)
* ❌ You need GraphQL support (consider urql or Apollo)

***

## Next Steps

<Cards>
  <Card title="Quick Start" description="Make your first request in under 2 minutes" href="/docs/caller/quick-start" />

  <Card title="Installation" description="Complete setup guide with all configuration options" href="/docs/caller/installation" />

  <Card title="Comparison" description="See how Caller compares to Axios, ky, and ofetch" href="/docs/caller/comparison" />

  <Card title="Request Builder" description="Deep dive into the fluent API for building requests" href="/docs/caller/builder" />

  <Card title="Schema Validation" description="Learn how to define type-safe API contracts" href="/docs/caller/schemas" />

  <Card title="Real-World Examples" description="Production-ready patterns for common API workflows" href="/docs/caller/real-world-examples" />
</Cards>


---

# Installation

> Complete guide to installing and configuring @igniter-js/caller. Covers all package managers, TypeScript setup, optional dependencies, and environment configuration.
URL: https://igniterjs.com/docs/caller/installation

## Prerequisites

Before installing Caller, ensure your environment meets these requirements:

| Requirement    | Minimum | Notes                            |
| -------------- | ------- | -------------------------------- |
| **Node.js**    | ≥ 18.0  | Native `fetch` support required  |
| **Bun**        | ≥ 1.0   | Alternative runtime              |
| **Deno**       | ≥ 1.40  | Alternative runtime              |
| **TypeScript** | ≥ 5.0   | Recommended for full type safety |

Caller works in **any environment** where `fetch` is available: Node.js 18+, Bun, Deno, Cloudflare Workers, Vercel Edge, and modern browsers.

***

## Install the Package

<Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
  <Tab value="npm">
    ```bash
    npm install @igniter-js/caller
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/caller
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/caller
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/caller
    ```
  </Tab>
</Tabs>

`@igniter-js/common` is installed automatically as a peer dependency.

***

## Optional Dependencies

Caller has a modular architecture — install only what you need:

### Schema Validation

To use schema-based type inference and runtime validation, install a StandardSchemaV1-compatible library:

<Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
  <Tab value="npm">
    ```bash
    npm install zod
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add zod
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add zod
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add zod
    ```
  </Tab>
</Tabs>

<Callout type="info" title="Any StandardSchemaV1 library works">
  While the examples use Zod, Caller supports **any** library that implements the [StandardSchemaV1](https://standardschema.dev) interface — including Valibot, ArkType, and custom schemas.
</Callout>

### Telemetry

For observability features (request tracing, metrics, event emission):

<Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
  <Tab value="npm">
    ```bash
    npm install @igniter-js/telemetry
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/telemetry
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/telemetry
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/telemetry
    ```
  </Tab>
</Tabs>

### React Integration

For React hooks (`useQuery`, `useMutate`), install React alongside Caller:

<Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
  <Tab value="npm">
    ```bash
    npm install react @igniter-js/caller
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add react @igniter-js/caller
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add react @igniter-js/caller
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add react @igniter-js/caller
    ```
  </Tab>
</Tabs>

<Callout type="warn" title="React 18+ required">
  The React client (`@igniter-js/caller/client`) requires React 18 or later. It uses hooks and the `useId` API.
</Callout>

***

## Create Your First Client

After installation, create a configured API client:

```typescript title="lib/api.ts"
import { IgniterCaller } from '@igniter-js/caller';

export const api = IgniterCaller.create()
  .withBaseUrl(process.env.API_URL || 'http://localhost:3000')
  .withHeaders({
    'Authorization': `Bearer ${process.env.API_TOKEN}`,
    'Content-Type': 'application/json',
  })
  .build();
```

<Callout type="success" title="Zero Configuration Required">
  Caller works out of the box with no configuration. If you just need to make HTTP requests, `IgniterCaller.create().build()` is all you need.
</Callout>

***

## Configuration Options

The `IgniterCallerBuilder` exposes a fluent, immutable API for configuring your client:

| Method                            | Purpose                                         |
| --------------------------------- | ----------------------------------------------- |
| `.withBaseUrl(url)`               | Prefix for all request URLs                     |
| `.withHeaders(headers)`           | Default headers merged into every request       |
| `.withCookies(cookies)`           | Default cookies (serialized as `Cookie` header) |
| `.withLogger(logger)`             | Logger instance for request lifecycle events    |
| `.withTelemetry(telemetry)`       | Telemetry manager for observability             |
| `.withSchemas(schemas, options?)` | Schema-based type safety and runtime validation |
| `.withRequestInterceptor(fn)`     | Transform requests before they are sent         |
| `.withResponseInterceptor(fn)`    | Transform responses after they are received     |
| `.withStore(adapter, options?)`   | Persistent store for caching (Redis, etc.)      |
| `.withMock(config)`               | Enable mock mode for testing                    |
| `.build()`                        | Finalize configuration and return the manager   |

Every `with*` method returns a **new builder instance** — the builder is fully immutable. This means you can safely create multiple derived clients from a base configuration:

```typescript
// Base client with shared auth
const base = IgniterCaller.create()
  .withHeaders({ 'Authorization': `Bearer ${token}` });

// Public API client
const api = base.withBaseUrl('https://api.example.com').build();

// Admin API client (different base URL, same auth)
const admin = base.withBaseUrl('https://admin.example.com').build();
```

***

## Project Structure

For larger projects, we recommend organizing your API configuration:

```
src/
├── lib/
│   ├── api.ts              # Core API client setup
│   └── schemas/
│       ├── index.ts        # Schema registry
│       ├── users.ts        # User-related schemas
│       └── products.ts     # Product-related schemas
├── callers/
│   └── facebook/           # CLI-generated clients
│       ├── index.ts
│       └── schema.ts
└── features/
    └── users/
        └── api.ts          # Feature-specific API helpers
```

### Monorepo Setup

In a monorepo with shared packages:

```typescript title="packages/api-client/src/index.ts"
import { IgniterCaller, IgniterCallerSchema } from '@igniter-js/caller';
import { sharedSchemas } from '@my-org/schemas';

export const api = IgniterCaller.create()
  .withBaseUrl(process.env.API_URL!)
  .withSchemas(sharedSchemas, { mode: 'strict' })
  .withRequestInterceptor(async (config) => ({
    ...config,
    headers: {
      ...config.headers,
      'X-Client-Id': 'web',
    },
  }))
  .build();
```

***

## Environment Configuration

Caller doesn't require any environment variables by default, but here's a typical setup:

```bash title=".env"
API_URL=https://api.example.com/v1
API_TOKEN=your-api-token
```

```typescript title="lib/api.ts"
import { IgniterCaller } from '@igniter-js/caller';

export const api = IgniterCaller.create()
  .withBaseUrl(process.env.API_URL!)
  .withHeaders({
    'Authorization': `Bearer ${process.env.API_TOKEN}`,
  })
  .build();
```

### Next.js Configuration

For Next.js applications, use the appropriate variable prefix:

```bash title=".env.local"
NEXT_PUBLIC_API_URL=https://api.example.com/v1
```

```typescript title="lib/api.ts"
export const api = IgniterCaller.create()
  .withBaseUrl(process.env.NEXT_PUBLIC_API_URL || '/api')
  .build();
```

<Callout type="info" title="Server vs Client">
  In Next.js App Router, you can use Caller in both Server Components (direct `.execute()`) and Client Components (via the React provider). Server-side usage doesn't need `NEXT_PUBLIC_` prefix — use regular `process.env` variables.
</Callout>

***

## TypeScript Configuration

Caller requires no special TypeScript configuration. The default `strict: true` setting provides the best type inference experience:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}
```

### Path Aliases

If you use path aliases, ensure they resolve correctly:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

***

## Common Issues

<Accordions>
  <Accordion title="fetch is not defined">
    This occurs when running Caller in a Node.js version older than 18, or in an environment that doesn't provide global `fetch`.

    **Solutions:**

    1. Upgrade to Node.js 18 or later (recommended)
    2. Install a polyfill:
       ```bash
       npm install node-fetch
       ```
    3. If using Bun or Deno, global `fetch` is built-in — no polyfill needed
  </Accordion>

  <Accordion title="Type inference is too slow or times out">
    Complex schema maps with many nested types can cause TypeScript to hit instantiation depth limits.

    **Solutions:**

    1. Split large schema maps into smaller, composable registries
    2. Use `$Infer` helpers to extract types explicitly instead of relying on deep inference
    3. Ensure `skipLibCheck: true` is set in `tsconfig.json` for faster builds
  </Accordion>

  <Accordion title="Module not found: @igniter-js/caller/client">
    The React client is exposed through a **subpath export**. Make sure your bundler/TypeScript resolves subpath exports:

    ```typescript
    // ✅ Correct
    import { IgniterCallerProvider } from '@igniter-js/caller/client';

    // ❌ Incorrect — internal path, may break
    import { IgniterCallerProvider } from '@igniter-js/caller/dist/client';
    ```

    If you're using an older bundler, ensure `moduleResolution` is set to `bundler` or `node16`.
  </Accordion>

  <Accordion title="React hooks error: IgniterCallerProvider is missing">
    You're using `useIgniterCaller()` or `.useQuery()` without wrapping your component tree in `<IgniterCallerProvider>`.

    ```tsx title="app/layout.tsx"
    import { IgniterCallerProvider } from '@igniter-js/caller/client';
    import { api } from '@/lib/api';

    export default function RootLayout({ children }) {
      return (
        <IgniterCallerProvider callers={{ main: api }}>
          {children}
        </IgniterCallerProvider>
      );
    }
    ```
  </Accordion>

  <Accordion title="Zod validation fails but data looks correct">
    Check your validation mode. In `'loose'` mode, Caller logs warnings instead of rejecting the request. In `'none'` mode, no validation happens at all.

    ```typescript
    // Strict mode — rejects mismatched responses
    const api = IgniterCaller.create()
      .withSchemas(schemas, { mode: 'strict' })
      .build();

    // Verify mode is set as expected
    ```
  </Accordion>

  <Accordion title="Caching doesn't persist across deployments">
    By default, Caller uses **in-memory** caching. For persistent caching across deployments or multiple instances, configure a store adapter:

    ```typescript
    const api = IgniterCaller.create()
      .withStore(redisAdapter, {
        ttl: 3600,
        keyPrefix: 'api-cache:',
      })
      .build();
    ```
  </Accordion>
</Accordions>

***

## Next Steps

<Cards>
  <Card title="Quick Start" description="Make your first request in under 2 minutes" href="/docs/caller/quick-start" />

  <Card title="Comparison" description="See how Caller compares to Axios, ky, and ofetch" href="/docs/caller/comparison" />

  <Card title="Core Concepts" description="Deep dive into the builder pattern and request lifecycle" href="/docs/caller/builder" />

  <Card title="Schema Validation" description="Add end-to-end type safety with Zod schemas" href="/docs/caller/schemas" />
</Cards>


---

# Quick Start

> Make your first type-safe HTTP request with Caller in under 2 minutes. Step-by-step guide covering installation, client creation, and common patterns.
URL: https://igniterjs.com/docs/caller/quick-start

This guide walks you through creating your first Caller client and making requests. By the end, you'll have a working API client with type-safe responses.

<Steps>
  <Step>
    ### Install Caller

    <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
      <Tab value="npm">
        ```bash
        npm install @igniter-js/caller
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @igniter-js/caller
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @igniter-js/caller
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @igniter-js/caller
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Create Your Client

    Create a shared API client instance. This is typically done once at application startup:

    ```typescript title="lib/api.ts"
    import { IgniterCaller } from '@igniter-js/caller';

    export const api = IgniterCaller.create()
      .withBaseUrl('https://jsonplaceholder.typicode.com')
      .withHeaders({
        'Content-Type': 'application/json',
      })
      .build();
    ```

    <Callout type="success" title="Minimal setup">
      For the simplest case, you can skip all configuration:

      ```typescript
      const api = IgniterCaller.create().build();
      ```

      This works anywhere `fetch` is available.
    </Callout>
  </Step>

  <Step>
    ### Make Your First GET Request

    ```typescript
    import { api } from './lib/api';

    async function fetchUsers() {
      const result = await api.get('/users').execute();

      if (result.error) {
        console.error('Failed to fetch users:', result.error.message);
        return [];
      }

      // result.data is the parsed response body
      console.log(`Fetched ${result.data.length} users`);
      return result.data;
    }
    ```

    <Callout type="warn" title="Never-throw by default">
      Caller **never throws** on HTTP error statuses (like 404 or 500). Instead, it returns an `error` object in the result envelope. It only throws on network failures or configuration errors.
    </Callout>
  </Step>

  <Step>
    ### Add Query Parameters

    Use `.params()` to add both path parameters and query string parameters:

    ```typescript
    // Path parameters — :id is replaced
    const user = await api.get('/users/:id')
      .params({ id: '1' })
      .execute();
    // Requests: GET /users/1

    // Query parameters — added to the URL
    const filtered = await api.get('/users')
      .params({ page: 1, limit: 10, status: 'active' })
      .execute();
    // Requests: GET /users?page=1&limit=10&status=active
    ```

    Any params not matching path segments are automatically appended as query string parameters.
  </Step>

  <Step>
    ### Send Data with POST

    ```typescript
    async function createUser(name: string, email: string) {
      const result = await api.post('/users')
        .body({ name, email })
        .execute();

      if (result.error) {
        // Handle validation errors, conflicts, etc.
        if (result.status === 409) {
          throw new Error('User already exists');
        }
        throw result.error;
      }

      // result.status is 201 for successful creation
      console.log('Created user:', result.data.id);
      return result.data;
    }
    ```
  </Step>

  <Step>
    ### Update and Delete Resources

    ```typescript
    // PUT — replace entire resource (idempotent)
    const updated = await api.put('/users/:id')
      .params({ id: '1' })
      .body({ name: 'Jane Doe', email: 'jane@example.com' })
      .execute();

    // PATCH — partial update
    const patched = await api.patch('/users/:id')
      .params({ id: '1' })
      .body({ name: 'Jane Updated' })
      .execute();

    // DELETE — remove resource
    const deleted = await api.delete('/users/:id')
      .params({ id: '1' })
      .execute();

    if (!deleted.error) {
      console.log('User deleted successfully');
    }
    ```
  </Step>
</Steps>

***

## Adding Resilience

Production applications need to handle transient failures. Caller provides retries, timeouts, and fallbacks out of the box:

```typescript
// Retry up to 3 times with exponential backoff
const result = await api.get('/external-service')
  .retry(3, {
    backoff: 'exponential',
    baseDelay: 500,
    retryOnStatus: [502, 503, 504],
  })
  .timeout(10000)        // 10 second timeout
  .fallback(() => [])    // Return empty array if all retries fail
  .execute();
```

<Callout type="info" title="Retry defaults">
  By default, Caller retries on status codes `408`, `429`, `500`, `502`, `503`, and `504`. You can customize this with `retryOnStatus`.
</Callout>

***

## Adding Type Safety

The real power of Caller comes from schema-based type inference. Define your API contract once and get automatic TypeScript types everywhere:

```typescript
import { IgniterCaller, IgniterCallerSchema } from '@igniter-js/caller';
import { z } from 'zod';

// 1. Define your API schemas
const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

const schemas = IgniterCallerSchema.create()
  .path('/users/:id', (path) =>
    path.get({
      responses: {
        200: UserSchema,
        404: z.object({ message: z.string() }),
      },
    })
  )
  .path('/users', (path) =>
    path.get({
      responses: { 200: z.array(UserSchema) },
    })
    .post({
      request: z.object({
        name: z.string(),
        email: z.string().email(),
      }),
      responses: {
        201: UserSchema,
        400: z.object({ message: z.string() }),
      },
    })
  )
  .build();

// 2. Create your typed client
const api = IgniterCaller.create()
  .withBaseUrl('https://api.example.com')
  .withSchemas(schemas, { mode: 'strict' })
  .build();

// 3. Full type inference — no manual interfaces needed!
const user = await api.get('/users/:id')
  .params({ id: '1' })       // ✅ params are typed
  .execute();
// user.data is typed as { id: number; name: string; email: string } | null

const created = await api.post('/users')
  .body({ name: 'John', email: 'john@example.com' })  // ✅ body is typed
  .execute();
// created.data is typed as { id: number; name: string; email: string } | null
```

***

## Error Handling Patterns

Caller returns a `{ data, error }` envelope. Here are the most common patterns:

```typescript
// Pattern 1: Guard clause
const { data, error } = await api.get('/users').execute();
if (error) {
  console.error(`${error.code}: ${error.message}`);
  return;
}
// TypeScript knows data is defined here
console.log(data.length);

// Pattern 2: Inline with fallback
const { data } = await api.get('/users')
  .fallback(() => [])
  .execute();
// data is always defined
console.log(data.length);

// Pattern 3: Match on status
const result = await api.post('/users').body(payload).execute();
switch (result.status) {
  case 201: return result.data;
  case 400: throw new ValidationError(result.error);
  case 409: throw new ConflictError(result.error);
  default: throw result.error;
}
```

***

## Using with React

Caller provides first-class React hooks through the `/client` subpath:

```tsx title="app/providers.tsx"
import { IgniterCallerProvider } from '@igniter-js/caller/client';
import { api } from '@/lib/api';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <IgniterCallerProvider callers={{ main: api }}>
      {children}
    </IgniterCallerProvider>
  );
}
```

```tsx title="components/user-profile.tsx"
import { useIgniterCaller } from '@igniter-js/caller/client';

const useCaller = useIgniterCaller<{ main: typeof api }>();

function UserProfile({ id }: { id: string }) {
  const main = useCaller('main');

  const { data, isLoading, error, refetch } = main
    .get('/users/:id')
    .params({ id })
    .useQuery({ staleTime: 30_000 });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h1>{data?.name}</h1>
      <p>{data?.email}</p>
      <button onClick={() => refetch()}>Refresh</button>
    </div>
  );
}
```

***

## Next Steps

Now that you've made your first requests, explore the full capabilities:

<Cards>
  <Card title="Installation" description="Complete setup guide with all configuration options and troubleshooting" href="/docs/caller/installation" />

  <Card title="Request Builder" description="Master the fluent API — headers, timeouts, retries, caching, and more" href="/docs/caller/builder" />

  <Card title="Schema Validation" description="Define type-safe API contracts with Zod and automatic inference" href="/docs/caller/schemas" />

  <Card title="React Integration" description="React hooks for data fetching with automatic caching and invalidation" href="/docs/caller/react" />

  <Card title="Real-World Examples" description="Production-ready patterns for common API workflows" href="/docs/caller/real-world-examples" />

  <Card title="Comparison" description="See how Caller compares to Axios, ky, and ofetch" href="/docs/caller/comparison" />
</Cards>


---

# Real-World Examples

> Production-ready patterns for common API workflows. Covers authentication, CRUD operations, file uploads, pagination, external API integration, and more.
URL: https://igniterjs.com/docs/caller/real-world-examples

This page demonstrates production-ready patterns using `@igniter-js/caller`. Each example is complete, copy-paste ready, and grounded in real-world scenarios.

***

## 1. Authenticated API Client

How to build an API client with automatic token management, refresh logic, and auth error handling.

```typescript title="lib/api.ts"
import { IgniterCaller, IgniterCallerError } from '@igniter-js/caller';

// Shared auth state
let accessToken: string | null = null;
let refreshPromise: Promise<string> | null = null;

async function getAccessToken(): Promise<string> {
  if (accessToken) return accessToken;

  // Avoid concurrent refresh calls
  if (!refreshPromise) {
    refreshPromise = fetch('/api/auth/refresh', { credentials: 'include' })
      .then(r => r.json())
      .then(data => {
        accessToken = data.accessToken;
        return accessToken!;
      })
      .finally(() => {
        refreshPromise = null;
      });
  }

  return refreshPromise;
}

export const api = IgniterCaller.create()
  .withBaseUrl(process.env.API_URL!)

  // Inject auth token on every request
  .withRequestInterceptor(async (config) => {
    const token = await getAccessToken();
    return {
      ...config,
      headers: {
        ...config.headers,
        'Authorization': `Bearer ${token}`,
      },
    };
  })

  // Handle 401s — clear token and retry
  .withResponseInterceptor(async (response) => {
    if (response.status === 401) {
      accessToken = null; // Force token refresh on next request
    }
    return response;
  })

  .build();
```

**Usage:**

```typescript
// Token is automatically attached
const { data: user } = await api.get('/me')
  .stale(30_000) // Cache profile for 30 seconds
  .execute();

// If token expires, it's refreshed automatically
const { data: orders } = await api.get('/orders').execute();
```

***

## 2. CRUD Service with Validation

A complete CRUD service for a User resource, with schema validation and error handling.

```typescript title="services/user.service.ts"
import { IgniterCallerSchema } from '@igniter-js/caller';
import { z } from 'zod';
import type { api } from '@/lib/api';

// --- Schemas ---
const UserSchema = z.object({
  id: z.string(),
  name: z.string().min(1),
  email: z.string().email(),
  role: z.enum(['admin', 'user']),
  createdAt: z.string().datetime(),
});

const CreateUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

const UpdateUserSchema = z.object({
  name: z.string().min(1).optional(),
  email: z.string().email().optional(),
  role: z.enum(['admin', 'user']).optional(),
});

const PaginatedResponse = <T extends z.ZodTypeAny>(schema: T) =>
  z.object({
    data: z.array(schema),
    meta: z.object({
      page: z.number(),
      limit: z.number(),
      total: z.number(),
      totalPages: z.number(),
    }),
  });

export const userSchemas = IgniterCallerSchema.create()
  .path('/users', (path) =>
    path.get({
      responses: { 200: PaginatedResponse(UserSchema) },
    })
    .post({
      request: CreateUserSchema,
      responses: {
        201: UserSchema,
        400: z.object({ message: z.string(), errors: z.record(z.array(z.string())) }),
        409: z.object({ message: z.string() }),
      },
    })
  )
  .path('/users/:id', (path) =>
    path.get({
      responses: {
        200: UserSchema,
        404: z.object({ message: z.string() }),
      },
    })
    .patch({
      request: UpdateUserSchema,
      responses: {
        200: UserSchema,
        404: z.object({ message: z.string() }),
      },
    })
    .delete({
      responses: {
        204: undefined,
        404: z.object({ message: z.string() }),
      },
    })
  )
  .build();

// --- Service ---
export const UserService = {
  async list(page = 1, limit = 20) {
    const { data, error } = await api.get('/users')
      .params({ page, limit })
      .stale(10_000)
      .execute();

    if (error) throw error;
    return data!;
  },

  async getById(id: string) {
    const { data, error } = await api.get('/users/:id')
      .params({ id })
      .stale(30_000)
      .execute();

    if (error) {
      if (error.code === 'IGNITER_CALLER_HTTP_ERROR' && (error as any).statusCode === 404) {
        return null;
      }
      throw error;
    }
    return data!;
  },

  async create(input: z.infer<typeof CreateUserSchema>) {
    const { data, error, status } = await api.post('/users')
      .body(input)
      .execute();

    if (error) {
      if (status === 400) {
        throw new ValidationError('Invalid user data', (error as any).details);
      }
      if (status === 409) {
        throw new ConflictError('User already exists');
      }
      throw error;
    }
    return data!;
  },

  async update(id: string, input: z.infer<typeof UpdateUserSchema>) {
    const { data, error } = await api.patch('/users/:id')
      .params({ id })
      .body(input)
      .execute();

    if (error) throw error;
    return data!;
  },

  async remove(id: string): Promise<boolean> {
    const { error } = await api.delete('/users/:id')
      .params({ id })
      .execute();

    return !error;
  },
};

// Custom errors
class ValidationError extends Error {
  constructor(message: string, public errors: Record<string, string[]>) {
    super(message);
    this.name = 'ValidationError';
  }
}

class ConflictError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'ConflictError';
  }
}
```

***

## 3. File Upload with Progress

Handling file uploads with FormData, progress tracking, and timeout management.

```typescript title="services/upload.service.ts"
import { api } from '@/lib/api';

interface UploadResult {
  id: string;
  url: string;
  filename: string;
  size: number;
}

export async function uploadFile(
  file: File,
  onProgress?: (percent: number) => void,
): Promise<UploadResult> {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('folder', 'documents');

  const { data, error } = await api.post('/uploads')
    .body(formData)
    .timeout(120_000) // 2 minutes for large files
    .retry(2, { retryOnStatus: [502, 503] })
    .execute();

  if (error) {
    if (error.code === 'IGNITER_CALLER_TIMEOUT') {
      throw new Error('Upload timed out. File may be too large.');
    }
    throw error;
  }

  return data as UploadResult;
}

// Multiple files
export async function uploadMultipleFiles(
  files: File[],
): Promise<UploadResult[]> {
  const formData = new FormData();
  files.forEach((file, i) => {
    formData.append(`files[${i}]`, file);
  });

  const { data, error } = await api.post('/uploads/batch')
    .body(formData)
    .timeout(300_000) // 5 minutes for batch uploads
    .execute();

  if (error) throw error;
  return data as UploadResult[];
}

// Download with progress
export async function downloadFile(fileId: string): Promise<Blob> {
  const { data, error } = await api.get('/files/:id/download')
    .params({ id: fileId })
    .responseType<Blob>()
    .execute();

  if (error) throw error;
  return data!;
}
```

***

## 4. External API Integration (Stripe)

Integrating with a third-party API with error classification, retry strategy, and response normalization.

```typescript title="services/stripe.service.ts"
import { IgniterCaller } from '@igniter-js/caller';

const stripe = IgniterCaller.create()
  .withBaseUrl('https://api.stripe.com/v1')
  .withHeaders({
    'Authorization': `Bearer ${process.env.STRIPE_SECRET_KEY}`,
    'Stripe-Version': '2024-06-20',
  })
  .withRequestInterceptor(async (config) => ({
    ...config,
    headers: {
      ...config.headers,
      'Idempotency-Key': config.headers?.['Idempotency-Key'] || crypto.randomUUID(),
    },
  }))
  .build();

export async function createPaymentIntent(amount: number, currency = 'usd') {
  const body = new URLSearchParams({
    amount: String(amount),
    currency,
  });

  const { data, error } = await stripe.post('/payment_intents')
    .body(body)
    .headers({ 'Content-Type': 'application/x-www-form-urlencoded' })
    .retry(3, {
      backoff: 'exponential',
      baseDelay: 1000,
      retryOnStatus: [429, 500, 502, 503],
    })
    .execute();

  if (error) {
    throw classifyStripeError(error);
  }

  return data as PaymentIntent;
}

function classifyStripeError(error: any): Error {
  switch (error.statusCode) {
    case 400: return new StripeError('Invalid request', error.details);
    case 401: return new StripeError('Invalid API key', error.details);
    case 402: return new StripeError('Payment required', error.details);
    case 429: return new StripeError('Rate limited — please retry', error.details);
    default: return new StripeError('Stripe API error', error.details);
  }
}
```

***

## 5. Paginated Data Fetching

A reusable utility for fetching paginated APIs with cursor or offset-based pagination.

```typescript title="lib/pagination.ts"
import type { IgniterCallerManager } from '@igniter-js/caller';

interface PaginationParams {
  page?: number;
  limit?: number;
  cursor?: string;
}

interface PaginatedResponse<T> {
  data: T[];
  nextCursor?: string;
  hasMore: boolean;
  total?: number;
}

/**
 * Generic paginated fetcher. Works with both cursor-based and offset-based pagination.
 */
export async function fetchPaginated<T>(
  api: IgniterCallerManager<any>,
  path: string,
  params: PaginationParams = {},
): Promise<PaginatedResponse<T>> {
  const { data, error } = await api.get(path)
    .params(params as any)
    .stale(15_000)
    .retry(2)
    .execute();

  if (error) throw error;

  return data as PaginatedResponse<T>;
}

/**
 * Fetches all pages automatically (use with caution for large datasets).
 */
export async function fetchAllPages<T>(
  api: IgniterCallerManager<any>,
  path: string,
  pageSize = 50,
): Promise<T[]> {
  const results: T[] = [];
  let page = 1;

  while (true) {
    const response = await fetchPaginated<T>(api, path, {
      page,
      limit: pageSize,
    });

    results.push(...response.data);

    if (!response.hasMore) break;
    page++;
  }

  return results;
}
```

**Usage:**

```typescript
// Fetch a single page
const page1 = await fetchPaginated<User>(api, '/users', {
  page: 1,
  limit: 20,
});
console.log(`Page 1: ${page1.data.length} users, hasMore: ${page1.hasMore}`);

// Fetch all pages (with built-in retry and caching)
const allUsers = await fetchAllPages<User>(api, '/users', 50);
console.log(`Total users: ${allUsers.length}`);
```

***

## 6. Parallel Requests with Batch

Fetching multiple resources simultaneously using `IgniterCallerManager.batch()`.

```typescript title="services/dashboard.service.ts">
import { IgniterCallerManager } from '@igniter-js/caller';
import { api } from '@/lib/api';

interface DashboardData {
  stats: DashboardStats;
  recentOrders: Order[];
  activeUsers: User[];
  notifications: Notification[];
}

export async function loadDashboard(): Promise<DashboardData> {
  const [statsRes, ordersRes, usersRes, notifRes] =
    await IgniterCallerManager.batch([
      api.get('/dashboard/stats').stale(30_000).execute(),
      api.get('/orders').params({ limit: 5, sort: 'recent' }).stale(10_000).execute(),
      api.get('/users').params({ status: 'active', limit: 10 }).stale(30_000).execute(),
      api.get('/notifications').params({ unread: true, limit: 10 }).execute(),
    ]);

  // Handle partial failures gracefully
  return {
    stats: statsRes.data ?? { revenue: 0, orders: 0, users: 0 },
    recentOrders: ordersRes.data ?? [],
    activeUsers: usersRes.data ?? [],
    notifications: notifRes.error ? [] : notifRes.data ?? [],
  };
}

// Typed batch with heterogeneous results
async function loadUserContext(userId: string) {
  const [profile, permissions, preferences] =
    await IgniterCallerManager.batch([
      api.get('/users/:id').params({ id: userId }).execute(),
      api.get('/users/:id/permissions').params({ id: userId }).execute(),
      api.get('/users/:id/preferences').params({ id: userId }).stale(60_000).execute(),
    ]);

  return {
    profile: profile.data,
    permissions: permissions.data ?? [],
    preferences: preferences.data ?? getDefaultPreferences(),
  };
}
```

***

## 7. Optimistic Updates with React

React pattern for optimistic UI updates with rollback on failure.

```tsx title="components/todo-list.tsx"
import { useIgniterCaller } from '@igniter-js/caller/client';

const useCaller = useIgniterCaller<{ main: typeof api }>();

function TodoList() {
  const main = useCaller('main');

  const { data: todos, isLoading, refetch } = main
    .get('/todos')
    .useQuery({ staleTime: 5_000 });

  const handleToggle = async (todoId: string, completed: boolean) => {
    // Optimistically update
    const previousTodos = todos;
    // local state update logic here...

    const { error } = await main.patch('/todos/:id')
      .params({ id: todoId })
      .body({ completed })
      .execute();

    if (error) {
      // Rollback: restore previous state
      refetch();
    }
  };

  const handleDelete = async (todoId: string) => {
    // Optimistically remove
    const { error } = await main.delete('/todos/:id')
      .params({ id: todoId })
      .execute();

    if (error) {
      refetch(); // Rollback
    }
  };

  if (isLoading) return <div>Loading...</div>;

  return (
    <ul>
      {todos?.map(todo => (
        <li key={todo.id}>
          <input
            type="checkbox"
            checked={todo.completed}
            onChange={() => handleToggle(todo.id, !todo.completed)}
          />
          {todo.title}
          <button onClick={() => handleDelete(todo.id)}>Delete</button>
        </li>
      ))}
    </ul>
  );
}
```

***

## 8. Rate-Limited API Client

Handling APIs with rate limits by respecting `Retry-After` headers.

```typescript title="lib/rate-limited-api.ts">
import { IgniterCaller } from '@igniter-js/caller';

const rateLimitedApi = IgniterCaller.create()
  .withBaseUrl('https://api.third-party.com')
  .withHeaders({ 'X-API-Key': process.env.API_KEY! })

  .withResponseInterceptor(async (response) => {
    const headers = response.headers;

    if (headers) {
      const remaining = parseInt(headers.get('X-RateLimit-Remaining') || '0');
      const reset = parseInt(headers.get('X-RateLimit-Reset') || '0');

      // Log rate limit status
      console.debug(`Rate limit: ${remaining} remaining, resets at ${new Date(reset * 1000)}`);

      // If rate limited, wait and retry
      if (response.status === 429) {
        const retryAfter = parseInt(headers.get('Retry-After') || '60');
        console.warn(`Rate limited. Waiting ${retryAfter}s...`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));

        // Note: for automatic retry, use .retry() on individual requests
        // Interceptors return the original response — they don't retry
      }
    }

    return response;
  })
  .build();

// Usage with preemptive rate limit handling
export async function fetchWithRateLimit<T>(path: string) {
  return rateLimitedApi.get(path)
    .retry(5, {
      backoff: 'exponential',
      baseDelay: 1000,
      retryOnStatus: [429, 503],
    })
    .execute();
}
```

***

## 9. Server-Side API Client (Next.js App Router)

Using Caller in Next.js Server Components and Route Handlers.

```typescript title="lib/api-server.ts">
import { IgniterCaller } from '@igniter-js/caller';
import { cookies, headers } from 'next/headers';

/**
 * Server-side API client — runs on the server, never exposed to the browser.
 * Uses process.env directly (no NEXT_PUBLIC_ prefix needed).
 */
export const serverApi = IgniterCaller.create()
  .withBaseUrl(process.env.API_URL!)
  .withHeaders({
    'X-Service-Key': process.env.API_SERVICE_KEY!,
  })
  .build();

/**
 * Proxied API client — forwards client cookies/auth to the backend.
 */
export async function createAuthenticatedServerApi() {
  const cookieStore = await cookies();
  const headersList = await headers();

  return IgniterCaller.create()
    .withBaseUrl(process.env.API_URL!)
    .withCookies({
      'session': cookieStore.get('session')?.value || '',
    })
    .withHeaders({
      'X-Forwarded-For': headersList.get('x-forwarded-for') || '',
      'X-Service-Key': process.env.API_SERVICE_KEY!,
    })
    .build();
}
```

**Usage in a Server Component:**

```typescript title="app/users/page.tsx"
import { serverApi } from '@/lib/api-server';

export default async function UsersPage() {
  const { data: users } = await serverApi
    .get('/users')
    .params({ limit: 20 })
    .stale(60_000)
    .fallback(() => [])
    .execute();

  return (
    <ul>
      {users?.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}
```

***

## 10. Error Classification Utility

A reusable pattern for classifying and handling API errors.

```typescript title="lib/errors.ts">
import { IgniterCallerError } from '@igniter-js/caller';

export class ApiError extends Error {
  constructor(
    message: string,
    public code: string,
    public status?: number,
    public details?: unknown,
  ) {
    super(message);
    this.name = 'ApiError';
  }

  static from(error: unknown): ApiError {
    if (IgniterCallerError.is(error)) {
      return new ApiError(
        error.message,
        error.code,
        (error as any).statusCode,
        (error as any).details,
      );
    }

    if (error instanceof Error) {
      return new ApiError(error.message, 'UNKNOWN');
    }

    return new ApiError(String(error), 'UNKNOWN');
  }

  get isNotFound(): boolean { return this.status === 404; }
  get isUnauthorized(): boolean { return this.status === 401; }
  get isForbidden(): boolean { return this.status === 403; }
  get isValidationError(): boolean { return this.status === 400 || this.status === 422; }
  get isConflict(): boolean { return this.status === 409; }
  get isServerError(): boolean { return this.status !== undefined && this.status >= 500; }
  get isNetworkError(): boolean { return this.code === 'IGNITER_CALLER_UNKNOWN_ERROR'; }
  get isTimeout(): boolean { return this.code === 'IGNITER_CALLER_TIMEOUT'; }
}

// Usage
export async function safeRequest<T>(promise: Promise<{ data?: T; error?: any }>): Promise<T> {
  const { data, error } = await promise;
  if (error) throw ApiError.from(error);
  return data as T;
}
```

**Usage:**

```typescript
try {
  const user = await safeRequest(
    api.get('/users/:id').params({ id: '123' }).execute()
  );
} catch (error) {
  const apiError = ApiError.from(error);

  if (apiError.isNotFound) {
    redirect('/404');
  } else if (apiError.isUnauthorized) {
    redirect('/login');
  } else if (apiError.isTimeout) {
    showToast('Request timed out. Please try again.');
  } else {
    console.error('Unhandled API error:', apiError);
  }
}
```

***

## Next Steps

<Cards>
  <Card title="Request Builder" description="Master the fluent API for building requests" href="/docs/caller/builder" />

  <Card title="Schema Validation" description="Define type-safe API contracts with Zod" href="/docs/caller/schemas" />

  <Card title="React Integration" description="React hooks for data fetching and mutations" href="/docs/caller/react" />

  <Card title="Interceptors" description="Transform requests and responses globally" href="/docs/caller/interceptors" />

  <Card title="API Reference" description="Complete reference for all classes, methods, and types" href="/docs/caller/api-reference" />
</Cards>


---

# Schema Validation

> Achieve end-to-end type safety with Standard Schema. Define API contracts with Zod, get automatic TypeScript inference, and validate requests/responses at runtime.
URL: https://igniterjs.com/docs/caller/schemas

Schema validation is what makes Caller truly powerful. By defining your API contract using Zod (or any Standard Schema V1 compatible library), you get automatic runtime validation and perfect TypeScript inference — without writing a single interface by hand.

***

## Why Schema Validation?

Without schema validation, this is what happens:

```typescript
// ❌ Traditional approach — no type safety
const response = await fetch('/api/users/1');
const user = await response.json();
// user is any — no autocomplete, no validation
console.log(user.naem); // Typo! Runtime error.
```

With Caller schemas:

```typescript
// ✅ Caller approach — full type safety
const result = await api.get('/users/:id')
  .params({ id: '1' })
  .execute();
// result.data is fully typed — autocomplete works
// Runtime validation catches mismatches
```

***

## Quick Example

Here's a complete schema validation setup in under 50 lines:

```typescript
import { IgniterCaller, IgniterCallerSchema } from '@igniter-js/caller';
import { z } from 'zod';

// 1. Define your schemas
const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

// 2. Build the schema registry
const schemas = IgniterCallerSchema.create()
  .path('/users', (path) =>
    path.get({
      responses: { 200: z.array(UserSchema) },
    })
    .post({
      request: z.object({
        name: z.string(),
        email: z.string().email(),
      }),
      responses: {
        201: UserSchema,
        400: z.object({ message: z.string() }),
      },
    })
  )
  .path('/users/:id', (path) =>
    path.get({
      responses: {
        200: UserSchema,
        404: z.object({ message: z.string() }),
      },
    })
    .delete({
      responses: {
        204: undefined,
        404: z.object({ message: z.string() }),
      },
    })
  )
  .build();

// 3. Create the typed client
const api = IgniterCaller.create()
  .withBaseUrl('https://api.example.com')
  .withSchemas(schemas, { mode: 'strict' })
  .build();

// 4. Enjoy full type inference!
const { data } = await api.get('/users/:id')
  .params({ id: '1' })
  .execute();
// data: { id: number; name: string; email: string } | null
```

***

## Schema Builder API

### `IgniterCallerSchema`

The root builder for defining your API contract.

```typescript
IgniterCallerSchema.create()
  .schema(key, schema)     // Register reusable schemas
  .path('/path', builder)  // Define path with HTTP methods
  .build();                // Build the final schema map
```

### Registering Reusable Schemas

Use `.schema()` to register schemas in a shared registry:

```typescript
const schemas = IgniterCallerSchema.create()
  .schema('User', z.object({
    id: z.number(),
    name: z.string(),
    email: z.string().email(),
  }))
  .schema('PaginationMeta', z.object({
    page: z.number(),
    total: z.number(),
    hasMore: z.boolean(),
  }))
  .path('/users/:id', (path) =>
    path.get({
      responses: {
        200: path.ref('User').schema,  // Reference by key
        404: z.object({ message: z.string() }),
      },
    })
  )
  .build();
```

### Schema Wrappers

`.ref(key)` returns a helper with Zod-based wrappers:

| Method              | Description      | Example Output                     |
| ------------------- | ---------------- | ---------------------------------- |
| `.schema`           | The schema as-is | `UserSchema`                       |
| `.array()`          | Array wrapper    | `z.array(UserSchema)`              |
| `.nullable()`       | Nullable wrapper | `UserSchema.nullable()`            |
| `.optional()`       | Optional wrapper | `UserSchema.optional()`            |
| `.record(keyType?)` | Record wrapper   | `z.record(z.string(), UserSchema)` |

```typescript
.path('/users', (path) =>
  path.get({
    responses: {
      // Array of users
      200: path.ref('User').array(),
      // Nullable response
      401: path.ref('Error').nullable().schema,
    },
  })
)
```

### Defining Path Methods

Each path can define multiple HTTP methods. Each method accepts a config object with:

| Property    | Type                               | Description                            |
| ----------- | ---------------------------------- | -------------------------------------- |
| `request`   | `StandardSchemaV1`                 | Schema for validating the request body |
| `responses` | `Record<number, StandardSchemaV1>` | Status-code-keyed response schemas     |

```typescript
.path('/users/:id', (path) =>
  path
    .get({ responses: { 200: UserSchema } })
    .put({
      request: UpdateUserSchema,
      responses: {
        200: UserSchema,
        404: z.object({ message: z.string() }),
      },
    })
    .patch({
      request: PartialUserSchema,
      responses: { 200: UserSchema },
    })
    .delete({
      responses: {
        204: undefined, // No content
        404: z.object({ message: z.string() }),
      },
    })
)
```

***

## Using Schemas

### Basic Usage

Pass your built schemas to the caller builder:

```typescript
const api = IgniterCaller.create()
  .withBaseUrl('https://api.example.com')
  .withSchemas(schemas, { mode: 'strict' })
  .build();
```

### Inline Schemas

You can also define schemas directly, without building a separate registry:

```typescript
const api = IgniterCaller.create()
  .withSchemas({
    '/users': {
      GET: {
        responses: { 200: z.array(UserSchema) },
      },
    },
    '/users/:id': {
      GET: {
        responses: {
          200: UserSchema,
          404: ErrorSchema,
        },
      },
    },
  })
  .build();
```

### Validation Modes

| Mode       | Behavior                                                                                                                                 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `'strict'` | **(Default)** Rejects the request if the response doesn't match the schema. Returns a `IGNITER_CALLER_RESPONSE_VALIDATION_FAILED` error. |
| `'loose'`  | Logs a warning but still returns the data if validation fails. Useful during migration.                                                  |
| `'none'`   | Disables all runtime validation. TypeScript inference still works.                                                                       |

```typescript
// Strict mode (default) — fails on schema mismatch
const strict = IgniterCaller.create()
  .withSchemas(schemas, { mode: 'strict' })
  .build();

// Loose mode — warns but continues
const loose = IgniterCaller.create()
  .withSchemas(schemas, { mode: 'loose' })
  .build();
```

***

## Type Inference with `$Infer`

The `.build()` result includes non-enumerable `$Infer` and `get` helpers for extracting types:

```typescript
const schemas = IgniterCallerSchema.create()
  .path('/users/:id', (path) =>
    path.get({
      responses: {
        200: UserSchema,
        404: ErrorSchema,
      },
    })
  )
  .build();

// Extract types without requesting
type GetUserResponse = ReturnType<
  typeof schemas.$Infer.Response<'/users/:id', 'GET', 200>
>;
// Type: { id: number; name: string; email: string }

type GetUserRequest = ReturnType<
  typeof schemas.$Infer.Request<'/users/:id', 'GET'>
>;

// Runtime getters for schema objects
const pathSchemas = schemas.get.path('/users/:id');
const getEndpoint = schemas.get.endpoint('/users/:id', 'GET');
const requestSchema = schemas.get.request('/users/:id', 'GET');
const responseSchema = schemas.get.response('/users/:id', 'GET', 200);
```

### Available Inference Methods

| Method                                 | Description                     |
| -------------------------------------- | ------------------------------- |
| `$Infer.Path<'/path'>`                 | All methods for a path          |
| `$Infer.Endpoint<'/path', 'GET'>`      | Single endpoint config          |
| `$Infer.Request<'/path', 'POST'>`      | Request body type               |
| `$Infer.Response<'/path', 'GET', 200>` | Response body for a status code |
| `$Infer.Responses<'/path', 'GET'>`     | All response statuses           |
| `$Infer.Schema<'User'>`                | Registered schema by key        |

***

## Content Type Validation

Schema validation only runs for **text-based content types**:

* `application/json`
* `text/xml` / `application/xml`
* `text/csv`

Binary responses (Blobs, Streams, ArrayBuffers, FormData) are **skipped** for validation. Use `.responseType<T>()` for typing only:

```typescript
// Binary response — no validation, typing only
const { data: file } = await api.get('/files/:id')
  .responseType<Blob>()
  .execute();
```

***

## Error Handling with Schemas

When validation fails in strict mode, you get a structured error:

```typescript
const result = await api.get('/users/:id')
  .params({ id: '1' })
  .execute();

if (result.error && IgniterCallerError.is(result.error)) {
  switch (result.error.code) {
    case 'IGNITER_CALLER_RESPONSE_VALIDATION_FAILED':
      // The server returned data that doesn't match the schema
      console.error('API contract mismatch:', result.error.details);
      break;
    case 'IGNITER_CALLER_REQUEST_VALIDATION_FAILED':
      // The request body failed validation
      console.error('Invalid request:', result.error.details);
      break;
    case 'IGNITER_CALLER_SCHEMA_INVALID':
      // Your schema definition has an error
      console.error('Schema error:', result.error.message);
      break;
  }
}
```

***

## Schema Organization

For large APIs, split schemas across files:

```typescript title="lib/schemas/index.ts"
import { IgniterCallerSchema } from '@igniter-js/caller';
import { userPaths } from './users';
import { productPaths } from './products';

export const schemas = IgniterCallerSchema.create()
  // Register shared schemas
  .schema('User', userSchema)
  .schema('Product', productSchema)

  // Compose paths from modules
  .path('/users/:id', userPaths.getById)
  .path('/users', userPaths.list)
  .path('/users', userPaths.create)
  .path('/products/:id', productPaths.getById)

  .build();
```

```typescript title="lib/schemas/users.ts"
import { z } from 'zod';
import type { IgniterCallerSchemaPathBuilder } from '@igniter-js/caller';

export const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

export const userPaths = {
  getById: (path: ReturnType<IgniterCallerSchemaPathBuilder['ref']> extends infer R ? any : never) => { /* ... */ },
  // This pattern works well when using the builder with explicit composition
} as const;
```

<Callout type="info" title="Alternative pattern">
  For simpler cases, just define your whole schema in one file. Split only when the file exceeds 200+ lines.
</Callout>

***

## Best Practices

<Callout type="success" title="Schema Design Guidelines">
  * **Use strict mode in production** — catches API contract mismatches before they cause subtle bugs
  * **Use loose mode during development** — helpful when iterating on APIs that aren't final
  * **Register shared schemas** — avoid duplicating User, Error, and Pagination schemas across paths
  * **Define error schemas** — always include error responses (400, 401, 404, 500) for comprehensive typing
  * **Use path parameters** — `:id` in URL patterns provides typed params and automatic matching
  * **Keep schemas near the API client** — co-locate in `lib/api/` or `lib/schemas/`
</Callout>

<Callout type="warn" title="Common Mistakes">
  * **Don't** forget that path must start with `/` — `'users'` will throw `IGNITER_CALLER_SCHEMA_INVALID`
  * **Don't** define the same path+method twice — throws `IGNITER_CALLER_SCHEMA_DUPLICATE`
  * **Don't** expect validation on binary responses — Blobs, streams, and files skip validation
  * **Don't** use `withSchemas()` without Zod installed — schema validation requires a StandardSchemaV1 library
</Callout>

***

## Supported Schema Libraries

Caller uses the [StandardSchemaV1](https://standardschema.dev) interface. Any library implementing this interface works:

| Library     | Version | Notes                                  |
| ----------- | ------- | -------------------------------------- |
| **Zod**     | ≥ 4.2   | Fully supported. Used in all examples. |
| **Valibot** | ≥ 1.0   | Exports `StandardSchemaV1` interface   |

<Callout type="info" title="Custom schemas">
  You can implement your own schemas by conforming to the `StandardSchemaV1` interface (`~standard`, `~validate`). See the [Standard Schema spec](https://standardschema.dev) for details.
</Callout>

***

## Next Steps

<Cards>
  <Card title="API Reference" description="Complete reference for all schema types and methods" href="/docs/caller/api-reference" />

  <Card title="CLI Generation" description="Generate schemas automatically from OpenAPI specs" href="/docs/caller/cli" />

  <Card title="Real-World Examples" description="See complete schema examples in production scenarios" href="/docs/caller/real-world-examples" />

  <Card title="Interceptors" description="Add auth tokens and transform responses globally" href="/docs/caller/interceptors" />
</Cards>


---

# Telemetry

> Monitor your API health and performance with native telemetry.
URL: https://igniterjs.com/docs/caller/telemetry

Caller is built with observability as a first-class citizen. It integrates deeply with `@igniter-js/telemetry` to provide tracing and metrics for every request.

## Setup

Attaching a telemetry manager is done during the Caller construction.

```ts
import { IgniterTelemetry } from '@igniter-js/telemetry'
import { IgniterCaller } from '@igniter-js/caller'
import { IgniterCallerTelemetryEvents } from '@igniter-js/caller/telemetry'

const telemetry = IgniterTelemetry.create()
  .withService('billing-service')
  .addEvents(IgniterCallerTelemetryEvents)
  .build()

export const api = IgniterCaller.create()
  .withTelemetry(telemetry)
  .build()
```

## Tracked Events

Caller automatically emits the following events:

| Event                                    | Metadata                                                      | Description                                |
| ---------------------------------------- | ------------------------------------------------------------- | ------------------------------------------ |
| `igniter.caller.request.execute.started` | `method`, `url`, `baseUrl`, `timeoutMs`                       | Emitted before the fetch starts.           |
| `igniter.caller.request.execute.success` | `method`, `url`, `durationMs`, `status`, `contentType`, `hit` | Emitted on successful response.            |
| `igniter.caller.request.execute.error`   | `method`, `url`, `durationMs`, `code`, `message`, `status`    | Emitted on HTTP or Network failure.        |
| `igniter.caller.cache.read.hit`          | `method`, `url`, `key`, `staleTime`                           | Emitted when data is retrieved from cache. |
| `igniter.caller.retry.attempt.started`   | `method`, `url`, `attempt`, `maxAttempts`, `delayMs`          | Emitted before each retry attempt.         |

## Context Injection

Telemetry attributes are automatically prefixed with domain-specific contexts:

* `ctx.request.*` — Request details (method, url)
* `ctx.response.*` — Response metadata (status, contentType)
* `ctx.cache.*` — Caching information
* `ctx.retry.*` — Retry attempts
* `ctx.error.*` — Error codes and messages

## Custom Telemetry

If you have custom interceptors, you can also manually emit events using the `telemetry` instance provided in the context.

```ts
api.withRequestInterceptor(async (request, context) => {
  context.telemetry.emit('my.custom.event', { foo: 'bar' })
  return request
})
```

***

## Log Integration

Caller also supports standard logging via `.withLogger()`. Telemetry is preferred for structured data and tracing, while Logger is best for human-readable console output.


---

# Mocking & Testing

> Test your application logic without making real HTTP calls.
URL: https://igniterjs.com/docs/caller/testing

Testing code that depends on network requests can be difficult and slow. Caller provides `IgniterCallerMock` to create high-fidelity, type-safe mocks of your API.

## Basic Mocking

You can swap a real caller for a mocked one in your testing environment.

```ts
import { IgniterCaller, IgniterCallerMock } from '@igniter-js/caller'

const mock = IgniterCallerMock.create()
  .mock('/users/:id', {
    GET: {
      response: { id: '1', name: 'Mock User' },
      status: 200,
    }
  })
  .build()

const api = IgniterCaller.create()
  .withMock({ enabled: true, mock })
  .build()
```

## Dynamic Mock Handlers

If you need logic in your mocks, pass a function instead of an object. The function receives the full request context.

```ts
const mock = IgniterCallerMock.create()
  .mock('/users/:id', {
    GET: (request) => ({
      response: { id: request.params.id, name: 'User ' + request.params.id },
      status: 200,
      delayMs: 100, // Simulate network latency
    })
  })
  .build()
```

## Mocking with Schemas

When using schemas, your mock responses are validated against the schema, ensuring your tests catch potential API contract breakages.

```ts
import { myApiSchemas } from './schema'

const mock = IgniterCallerMock.create()
  .withSchemas(myApiSchemas)
  .mock('/me', {
    GET: { response: { name: 'Lia' } } // This will error if 'name' is not in schema
  })
  .build()
```

## Using in Vitest/Jest

Common pattern for unit testing:

```ts
import { describe, it, expect, beforeEach } from 'vitest'
import { api } from '@/lib/api'

describe('UserService', () => {
  it('should fetch user correctly', async () => {
    // Enable mock mode for this test
    api.config.set('mock', { enabled: true, mock: myTestMock })
    
    const user = await UserService.get('1')
    expect(user.name).toBe('Mock User')
  })
})
```

***

## Error Handling

Mocks can also simulate errors:

```ts
mock.mock('/forbidden', {
  GET: { status: 403, response: { message: 'No access' } }
})
```


---

# Add-ons

> All 9 Igniter.js add-ons — database, auth, jobs, store, MCP, logging, telemetry, bots, and shadcn/ui. Options, inline notation, dependencies, and env vars.
URL: https://igniterjs.com/docs/cli/add-ons

## Add-ons

Add-ons are modular features you can layer onto any starter. They configure dependencies, environment variables, Docker services, and source code templates — all from a single `--add-ons` flag.

<Callout type="info">
  Add-ons are applied in **registration order** during `igniter init`, and their effects are cumulative. Adding `database,auth` configures both with shared wiring — the auth module references the database connection automatically.
</Callout>

***

## Add-on Catalog

| Add-on        | Value       | Has Options | Docker | Description                                            |
| ------------- | ----------- | ----------- | ------ | ------------------------------------------------------ |
| **Database**  | `database`  | Yes         | Yes    | Prisma or Drizzle ORM + PostgreSQL, MySQL, or SQLite   |
| **Auth**      | `auth`      | Yes         | No     | Better Auth with 21 plugin options                     |
| **Jobs**      | `jobs`      | No          | Yes    | Background job processing with BullMQ + Redis          |
| **Store**     | `store`     | No          | Yes    | Redis-backed key-value caching and pub/sub             |
| **MCP**       | `mcp`       | No          | No     | Model Context Protocol server for AI agents            |
| **Logging**   | `logging`   | No          | No     | Structured logging with Pino                           |
| **Telemetry** | `telemetry` | No          | No     | OpenTelemetry tracing, metrics, and events             |
| **Bots**      | `bots`      | No          | No     | Multi-platform bot setup (Telegram, WhatsApp, Discord) |
| **shadcn/ui** | `shadcn-ui` | No          | No     | Run shadcn/ui initialization                           |

***

## Inline Option Notation

Add-ons with configurable options use a colon-separated, positional notation:

```
--add-ons "addon-id:option1:option2+value2"
```

* `:` separates positional options (order matters)
* `+` separates multiple values for multi-select options
* `,` separates different add-ons

***

## `database`

Database integration with choice of ORM and provider.

### Options

| Position | Key        | Type   | Values                          |
| -------- | ---------- | ------ | ------------------------------- |
| 1        | `orm`      | single | `prisma`, `drizzle`             |
| 2        | `provider` | single | `postgresql`, `mysql`, `sqlite` |

### Prisma Templates

| Template                                    | Output                 |
| ------------------------------------------- | ---------------------- |
| `add-ons/database/prisma/lib.hbs`           | `src/lib/database.ts`  |
| `add-ons/database/prisma/prisma.config.hbs` | `prisma.config.ts`     |
| `add-ons/database/prisma/schema.hbs`        | `prisma/schema.prisma` |

### Drizzle Templates

| Template                           | Output                |
| ---------------------------------- | --------------------- |
| `add-ons/database/drizzle/lib.hbs` | `src/lib/database.ts` |

### Prisma Dependencies

* `dotenv` (latest)
* `prisma` (^6.19.0)
* `@prisma/client` (^6.19.0)

### Docker (Provider)

| Provider   | Image                | Port        |
| ---------- | -------------------- | ----------- |
| PostgreSQL | `postgres:16-alpine` | `5432:5432` |
| MySQL      | `mysql:8.0`          | `3306:3306` |

### Environment Variables

| Variable            | PostgreSQL Default                                                    | MySQL Default                                                    | SQLite Default  |
| ------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | --------------- |
| `DATABASE_URL`      | `postgresql://igniter:${DATABASE_PASSWORD}@localhost:5432/igniter_db` | `mysql://igniter:${DATABASE_PASSWORD}@localhost:3306/igniter_db` | `file:./dev.db` |
| `DATABASE_PASSWORD` | `igniter`                                                             | `docker`                                                         | —               |
| `DATABASE_USER`     | `igniter`                                                             | `docker`                                                         | —               |
| `DATABASE_NAME`     | —                                                                     | `docker`                                                         | —               |

### Post-install Hook

* **Prisma:** Runs `prisma generate` after dependency installation
* **Drizzle:** Runs `drizzle init` after dependency installation

### Examples

```bash
# Prisma + PostgreSQL
igniter init app --add-ons "database:prisma:postgresql"

# Drizzle + MySQL
igniter init app --add-ons "database:drizzle:mysql"

# Drizzle + SQLite (no Docker needed)
igniter init app --add-ons "database:drizzle:sqlite"
```

***

## `auth`

Better Auth integration with comprehensive plugin support.

### Options

| Position | Key        | Type   | Values                        |
| -------- | ---------- | ------ | ----------------------------- |
| 1        | `provider` | single | `better-auth`                 |
| 2        | `plugins`  | multi  | 21 plugin options (see below) |

### Provider: Better Auth

**Dependencies:** `better-auth` (1.3.0)

**Template:** `add-ons/auth/better-auth/auth.hbs` → `src/lib/auth.ts`

**Post-install:** Runs `@better-auth/cli generate --config src/lib/auth.ts --yes`

### Available Plugins

`email`, `two-factor`, `username`, `anonymous`, `phone-number`, `magic-link`, `email-otp`, `passkey`, `generic-oauth`, `one-tap`, `api-key`, `admin`, `organization`, `oidc`, `sso`, `bearer`, `multi-session`, `oauth-proxy`, `open-api`, `jwt`, `next-cookies`

### Examples

```bash
# Basic auth with email + magic link
igniter init app --add-ons "auth:better-auth:email+magic-link"

# Advanced auth with passkey + 2FA + JWT
igniter init app --add-ons "auth:better-auth:email+passkey+two-factor+jwt"

# Auth + Database combined
igniter init app --add-ons "database:prisma:postgresql,auth:better-auth:email+magic-link"
```

***

## `jobs`

Background job processing with BullMQ and Redis.

**Dependencies:**

* `@igniter-js/adapter-redis` (latest)
* `@igniter-js/adapter-bullmq` (latest)
* `bullmq` (5.58.7)
* `ioredis` (5.6.1)

**Templates:**

* `add-ons/jobs/jobs.ts.hbs` → `src/services/jobs.ts`
* `add-ons/jobs/redis.ts.hbs` → `src/services/redis.ts`
* `add-ons/jobs/store.ts.hbs` → `src/services/store.ts`

**Docker:** `redis:7-alpine` on port `6379`

**Environment Variables:** `REDIS_URL`, `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `IGNITER_JOBS_QUEUE_PREFIX`

```bash
igniter init app --add-ons jobs
```

***

## `store`

Redis-backed key-value caching, sessions, and pub/sub messaging.

**Dependencies:**

* `@igniter-js/adapter-redis` (latest)
* `ioredis` (5.6.1)

**Templates:**

* `add-ons/store/redis.ts.hbs` → `src/services/redis.ts`
* `add-ons/store/store.ts.hbs` → `src/services/store.ts`

**Docker:** `redis:7-alpine` on port `6379`

**Environment Variables:** `REDIS_URL`, `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`

```bash
igniter init app --add-ons store
```

***

## `mcp`

Model Context Protocol server setup for AI agent integration.

**Templates:**

* `add-ons/mcp/mcp.ts.hbs` → `src/services/mcp.ts`
* `add-ons/mcp/nextjs/route-handler.hbs` (Next.js)
* `add-ons/mcp/tanstack-start/route-handler.hbs` (TanStack Start)

```bash
igniter init app --add-ons mcp
```

***

## `logging`

Structured logging with Pino.

**Template:** `add-ons/logging/logger.ts.hbs` → `src/services/logger.ts`

**Dependencies:** `@igniter-js/core` (latest)

```bash
igniter init app --add-ons logging
```

***

## `telemetry`

OpenTelemetry tracing, metrics, and events.

**Template:** `add-ons/telemetry/telemetry.ts.hbs`

**Dependencies:** `@igniter-js/core` (latest)

**Environment Variables:**

* `IGNITER_TELEMETRY_ENABLE_TRACING`
* `IGNITER_TELEMETRY_ENABLE_METRICS`
* `IGNITER_TELEMETRY_ENABLE_EVENTS`
* `IGNITER_TELEMETRY_ENABLE_CLI_INTEGRATION`

```bash
igniter init app --add-ons telemetry
```

***

## `bots`

Multi-platform bot setup for Telegram, WhatsApp, Discord, and more.

**Templates:**

* `add-ons/bots/sample-bot.hbs`
* `add-ons/bots/nextjs/route-handler.hbs` (Next.js)
* `add-ons/bots/tanstack-start/route-handler.hbs` (TanStack Start)

**Dependencies:** `@igniter-js/bot` (alpha)

**Environment Variables:** `TELEGRAM_TOKEN`, `TELEGRAM_WEBHOOK_URL`, `TELEGRAM_WEBHOOK_SECRET`

```bash
igniter init app --add-ons bots
```

***

## `shadcn-ui`

Initializes shadcn/ui components in your project.

**Post-install:** Runs `shadcn@latest init --base-color zinc --src-dir --silent --yes`

```bash
igniter init app --add-ons shadcn-ui
```

***

## Add-on Architecture

All add-ons extend `BaseAddOn` and implement a common interface:

```typescript
interface AddOn {
  name: string;           // Display name
  value: string;          // CLI identifier
  description: string;    // Short description
  hint: string;           // Prompt hint
  options?: AddOnOption[]; // Configurable options
  templates: Template[];  // Handlebars templates
  dependencies: Dep[];    // Package dependencies
  dockerServices: Service[]; // Docker services
  envVars: EnvVar[];      // Environment variables
  runSetup(dir, config): Promise<void>;      // Template + config setup
  runPostInstall(dir, config): Promise<void>; // Post-install hooks
}
```

### Setup Order

During `igniter init`, each add-on is applied in this order:

1. **Dependencies** → merged into `package.json`
2. **Docker services** → merged into `docker-compose.yml`
3. **Environment variables** → merged into `.env`
4. **Templates** → rendered and written to output paths
5. **Post-install** → CLI setup hooks (run AFTER dependencies are installed)

<Callout type="warn">
  Post-install hooks (like `prisma generate` and `better-auth generate`) run **only if dependencies are installed**. If `--no-install` is passed, these steps are skipped with a warning.
</Callout>

***

## Next Steps

<Cards>
  <Card title="Starters" description="Compare all 6 starters and understand which add-ons work with each." href="/docs/cli/starters" />

  <Card title="init Command" description="Full reference for the init command — modes, flags, and all options." href="/docs/cli/commands/init" />

  <Card title="Real-World Scenarios" description="Production-ready add-on combinations for common use cases." href="/docs/cli/real-world" />
</Cards>


---

# API Reference

> Complete reference for every CLI command, flag, option, and subcommand. Includes all supported values and default behaviors.
URL: https://igniterjs.com/docs/cli/api-reference

## API Reference

This page documents every command, flag, and option available in `@igniter-js/cli`. All defaults and behaviors are verified against the actual implementation in `packages/cli/src/`.

***

## Global Options

These apply to the top-level `igniter` command:

| Option      | Description                       |
| ----------- | --------------------------------- |
| `--help`    | Show help for the current command |
| `--version` | Show the CLI version (`0.0.1`)    |

***

## `igniter init`

```
igniter init [project-name] [options]
```

### Arguments

| Argument       | Type     | Required | Description                                                       |
| -------------- | -------- | -------- | ----------------------------------------------------------------- |
| `project-name` | `string` | No       | Name of the project directory. If omitted, prompts interactively. |

### Options

| Option                    | Type                                            | Default            | Description                                 |
| ------------------------- | ----------------------------------------------- | ------------------ | ------------------------------------------- |
| `--mode`                  | `"install" \| "new-project"`                    | `new-project`      | Operation mode                              |
| `--pm, --package-manager` | `"npm" \| "yarn" \| "pnpm" \| "bun"`            | auto-detected      | Package manager                             |
| `--template`              | `string`                                        | interactive prompt | Starter template                            |
| `--add-ons`               | `string`                                        | —                  | Comma-separated add-ons with inline options |
| `--database`              | `"none" \| "postgresql" \| "mysql" \| "sqlite"` | —                  | Database provider (shorthand)               |
| `--no-git`                | flag                                            | `false`            | Skip git init                               |
| `--no-install`            | flag                                            | `false`            | Skip dependency installation                |
| `--no-docker`             | flag                                            | `false`            | Skip Docker setup                           |

### Template Values

| Value              | Framework      | Runtime | Type        |
| ------------------ | -------------- | ------- | ----------- |
| `nextjs`           | Next.js 15     | Node.js | Full-stack  |
| `tanstack-start`   | TanStack Start | Node.js | Full-stack  |
| `express-rest-api` | Express        | Node.js | Backend API |
| `bun-rest-api`     | Bun            | Bun     | Backend API |
| `bun-react-app`    | Bun + React    | Bun     | Full-stack  |
| `deno-rest-api`    | Deno           | Deno    | Backend API |

### Add-on Values

| Value       | Has Options | Description               |
| ----------- | ----------- | ------------------------- |
| `database`  | Yes         | ORM + provider selection  |
| `auth`      | Yes         | Better Auth + plugins     |
| `jobs`      | No          | Background job processing |
| `store`     | No          | Redis key-value store     |
| `mcp`       | No          | MCP server for AI agents  |
| `logging`   | No          | Structured logging        |
| `telemetry` | No          | OpenTelemetry             |
| `bots`      | No          | Multi-platform bots       |
| `shadcn-ui` | No          | shadcn/ui init            |

### Inline Add-on Notation

```
--add-ons "addon-id[:option1[:option2+value2]]"
```

| Separator | Purpose                      |
| --------- | ---------------------------- |
| `,`       | Separate add-ons             |
| `:`       | Separate positional options  |
| `+`       | Separate multi-select values |

***

## `igniter generate`

```
igniter generate <subcommand> [options]
```

### Subcommands

#### `generate feature`

```
igniter generate feature [name] [options]
```

| Option          | Type     | Default       | Description                                   |
| --------------- | -------- | ------------- | --------------------------------------------- |
| `[name]`        | `string` | interactive   | Feature name (kebab-case)                     |
| `--schema`      | `string` | —             | Schema provider + model (e.g., `prisma:User`) |
| `--schema-path` | `string` | auto-detected | Custom schema file path                       |

#### `generate controller`

```
igniter generate controller [name] [options]
```

| Option          | Type     | Default     | Description                  |
| --------------- | -------- | ----------- | ---------------------------- |
| `[name]`        | `string` | interactive | Controller name (kebab-case) |
| `-f, --feature` | `string` | interactive | Target feature name          |

#### `generate procedure`

```
igniter generate procedure [name] [options]
```

| Option          | Type     | Default     | Description                 |
| --------------- | -------- | ----------- | --------------------------- |
| `[name]`        | `string` | interactive | Procedure name (kebab-case) |
| `-f, --feature` | `string` | interactive | Target feature name         |

#### `generate docs`

```
igniter generate docs [options]
```

| Option     | Type     | Default                 | Description      |
| ---------- | -------- | ----------------------- | ---------------- |
| `--router` | `string` | `src/igniter.router.ts` | Router file path |
| `--output` | `string` | `./src/docs`            | Output directory |

#### `generate schema`

```
igniter generate schema [options]
```

| Option     | Type     | Default                 | Description      |
| ---------- | -------- | ----------------------- | ---------------- |
| `--router` | `string` | `src/igniter.router.ts` | Router file path |
| `--output` | `string` | `src/igniter.schema.ts` | Output file path |

#### `generate caller`

```
igniter generate caller [options]
```

| Option     | Type     | Default                  | Description        |
| ---------- | -------- | ------------------------ | ------------------ |
| `--name`   | `string` | interactive              | Caller name prefix |
| `--url`    | `string` | —                        | Remote OpenAPI URL |
| `--path`   | `string` | —                        | Local OpenAPI path |
| `--output` | `string` | `src/callers/<hostname>` | Output directory   |

***

## `igniter dev`

```
igniter dev [options]
```

| Option          | Type     | Default                 | Description           |
| --------------- | -------- | ----------------------- | --------------------- |
| `--router`      | `string` | `src/igniter.router.ts` | Router file path      |
| `--output`      | `string` | `src/igniter.schema.ts` | Schema output path    |
| `--docs-output` | `string` | `./src/docs`            | Docs output directory |
| `--cmd`         | `string` | auto-detected           | Dev server command    |

### Auto-detected Dev Commands

| Package Manager | Default Command |
| --------------- | --------------- |
| `npm`           | `npm run dev`   |
| `pnpm`          | `pnpm dev`      |
| `yarn`          | `yarn dev`      |
| `bun`           | `bun dev`       |

***

## Package Manager Detection

The CLI detects your package manager from `process.env.npm_config_user_agent`:

| User Agent Prefix | Package Manager | Executor   |
| ----------------- | --------------- | ---------- |
| `yarn/`           | `yarn`          | `yarn dlx` |
| `pnpm/`           | `pnpm`          | `pnpx`     |
| `bun/`            | `bun`           | `bunx`     |
| (any other)       | `npm`           | `npx`      |

***

## Framework Detection (Install Mode)

| Detection Rule                                         | Detected Framework |
| ------------------------------------------------------ | ------------------ |
| `next.config.js` or `next.config.ts` exists            | `nextjs`           |
| `@tanstack/react-start` in `package.json` dependencies | `tanstack-start`   |
| Neither matched                                        | `generic`          |

***

## Exit Codes

| Code | Meaning                                                         |
| ---- | --------------------------------------------------------------- |
| `0`  | Success                                                         |
| `1`  | Error (initialization failed, file not found, validation error) |

***

## Next Steps

<Cards>
  <Card title="Best Practices" description="Production patterns for init, generate, and dev workflows." href="/docs/cli/best-practices" />

  <Card title="Troubleshooting" description="Fix common errors — file not found, port conflicts, watcher issues." href="/docs/cli/troubleshooting" />

  <Card title="Real-World Scenarios" description="See the CLI in action across common production patterns." href="/docs/cli/real-world" />
</Cards>


---

# Best Practices

> Production-ready patterns and anti-patterns for the Igniter.js CLI. Learn when to use flags vs interactive mode, how to structure teams, and how to optimize CI/CD.
URL: https://igniterjs.com/docs/cli/best-practices

## Best Practices

This page covers recommended patterns for using `@igniter-js/cli` in production. Each recommendation is grounded in the actual implementation behavior.

***

## Init Best Practices

### ✅ Use Flags for Automation

For scripts, CI/CD, and onboarding docs, always use explicit flags instead of interactive prompts:

```bash
# ✅ Good: Deterministic, scriptable
igniter init my-saas \
  --template nextjs \
  --add-ons "database:prisma:postgresql,auth:better-auth:email+magic-link" \
  --pm pnpm \
  --no-git

# ❌ Bad: Requires human interaction
igniter init my-saas
```

### ✅ Pin the CLI Version in CI/CD

The `@latest` tag can introduce breaking changes. Pin to a specific version in automation:

```bash
# ✅ Good: Deterministic
npx @igniter-js/cli@0.0.1 init my-app --template nextjs

# ❌ Risky: May change behavior unexpectedly
npx @igniter-js/cli@latest init my-app --template nextjs
```

### ✅ Use Install Mode for Brownfield Projects

When adding Igniter.js to an existing project, always use `--mode install`:

```bash
# ✅ Good: Layers Igniter.js on top, doesn't overwrite
igniter init . --mode install --add-ons "database:prisma:postgresql"

# ❌ Bad: May overwrite existing files with a starter
igniter init . --template nextjs
```

### ❌ Don't Mix Interactive and Flag Mode

The CLI merges flags with interactive prompts. If you pass partial flags, you may still get prompted for missing values:

```bash
# ⚠️ Still prompts for add-on options
igniter init my-app --add-ons database

# ✅ Use full inline notation to avoid prompts
igniter init my-app --add-ons "database:prisma:postgresql"
```

***

## Generate Best Practices

### ✅ Generate Features from Schema

Schema-aware generation produces type-safe code that matches your database exactly:

```bash
# ✅ Good: Type-safe, schema-derived
igniter generate feature users --schema prisma:User

# ❌ Needs manual typing afterward
igniter generate feature users
```

### ✅ Keep Router Updated After Generation

New controllers and procedures need to be registered in the router:

```typescript
// After generating a feature or controller:
import { UsersController } from './features/users/controllers/users.controller';

export const igniterRouter = IgniterRouter.create()
  .addController(UsersController)  // ← Add this line
  .build();
```

### ✅ Run Schema and Docs Together

The `igniter dev` command handles both automatically, but for one-off generation, run both:

```bash
# ✅ Good: Both schema and docs updated
igniter generate schema && igniter generate docs

# ⚠️ Incomplete: Only schema, no docs
igniter generate schema
```

### ✅ Use Caller Generation for External APIs

Instead of manually typing API clients, generate them:

```bash
# ✅ Good: Type-safe, auto-updated
igniter generate caller --name stripe --url https://api.stripe.com/openapi.json

# ❌ Manual: Error-prone, needs maintenance
// Manually typed fetch calls...
```

***

## Dev Best Practices

### ✅ Always Use --cmd for Clarity

Even though the CLI auto-detects the dev command, explicit is better:

```bash
# ✅ Good: Clear intention
igniter dev --cmd "pnpm dev"

# ⚠️ Works but less explicit
igniter dev
```

### ✅ Keep Router File Version Controlled

The `igniter.schema.ts` is auto-generated from your router. Always commit both:

```bash
# ✅ Good: Both synced in version control
git add src/igniter.router.ts src/igniter.schema.ts

# ❌ Bad: Schema out of sync
git add src/igniter.router.ts
# forgets to add src/igniter.schema.ts
```

### ✅ Add .gitignore for Generated Docs

If you prefer not to commit generated docs:

```text
# .gitignore
src/docs/
src/callers/
```

### ❌ Don't Ignore File Change Warnings

When dev mode shows an error, investigate immediately — it usually means a controller or procedure has a type mismatch:

```
❌ Failed to regenerate: Type 'string' is not assignable to type 'number'
```

***

## Team Practices

### ✅ Standardize Init Commands

Create a project README or script with the exact init command:

````markdown
## Getting Started

```bash
igniter init my-app \
  --template nextjs \
  --add-ons "database:prisma:postgresql,auth:better-auth:email+magic-link,jobs" \
  --pm pnpm
````

````

### ✅ Use Package Manager Consistency

All team members should use the same package manager. The CLI auto-detects, but explicit `--pm` prevents surprises:

```bash
igniter init my-app --template nextjs --pm pnpm
````

### ✅ Commit the Generated Schema

The `igniter.schema.ts` file is the source of truth for client-side types. It should be committed and reviewed:

* **Commit it:** Ensures CI and new team members have consistent types
* **Review it:** Schema changes indicate API surface changes
* **Regenerate it:** Run `igniter generate schema` after router changes

***

## CI/CD Practices

### ✅ Validate Schema in CI

Add a CI step that verifies the schema is up to date:

```yaml
- name: Check schema is up to date
  run: |
    igniter generate schema
    if [ -n "$(git diff src/igniter.schema.ts)" ]; then
      echo "Schema is out of date. Run 'igniter generate schema' locally."
      exit 1
    fi
```

### ✅ Generate Callers in CI

For projects with external API dependencies, generate callers in CI:

```yaml
- name: Generate API callers
  run: |
    igniter generate caller --name stripe --url https://api.stripe.com/openapi.json
    igniter generate caller --name github --url https://api.github.com/openapi.json
```

***

## Security Practices

### ✅ Review Generated Code

Generated code (schema, callers, features) should be reviewed like any other code. The CLI generates safe defaults, but production specifics need human review.

### ❌ Don't Commit Secrets

The CLI adds environment variable placeholders to `.env`. Never commit the actual `.env` file with real secrets:

```text
# Always add
.env
.env.local
.env.production
```

***

## Next Steps

<Cards>
  <Card title="Troubleshooting" description="Common errors and their solutions — init failures, watcher issues, port conflicts." href="/docs/cli/troubleshooting" />

  <Card title="API Reference" description="Complete reference for every command, flag, and option." href="/docs/cli/api-reference" />

  <Card title="Real-World Scenarios" description="See all these practices applied in production scenarios." href="/docs/cli/real-world" />
</Cards>


---

# Introduction

> The official Igniter.js CLI. Create projects, scaffold features, wire add-ons, and keep schema + docs in sync — all from the terminal.
URL: https://igniterjs.com/docs/cli

## Overview

`@igniter-js/cli` is the **command-line interface for Igniter.js**. It is your single entry point for creating new projects, scaffolding features from database schemas, wiring add-ons (database, auth, jobs, and more), and keeping your TypeScript client schema and OpenAPI docs synchronized as you code.

No boilerplate. No manual wiring. One command, and you have a working project.

<Callout type="info">
  The CLI is designed for **speed and consistency across teams**. Every command follows predictable conventions — same flags, same output structure, same template engine — so onboarding new developers takes minutes, not hours.
</Callout>

### Key Capabilities

* **Project Creation** — `igniter init` creates a project with any of 6 starters (Next.js, TanStack Start, Express, Bun, Deno) plus 9 configurable add-ons
* **Schema-aware Scaffolding** — `igniter generate feature --schema prisma:User` reads your Prisma schema and generates type-safe controllers, procedures, and interfaces
* **Auto-regeneration** — `igniter dev` watches your router and features, then regenerates the client schema and OpenAPI spec on every change
* **OpenAPI Client Generation** — `igniter generate caller` takes any OpenAPI spec and produces a fully typed, Zod-validated Igniter Caller
* **Multi-runtime** — starters target different runtimes; add-ons adapt based on the detected framework
* **Extensible** — starters, add-ons, and schema providers are registry-based; the community can add new ones

***

## Architecture

The CLI is structured around three top-level commands, each backed by a composable architecture of registries, template engines, and file watchers.

```
igniter
├── init           ← Create a new project or install into existing
│   ├── Starters   (6: nextjs, tanstack-start, express, bun-api, bun-react, deno)
│   ├── Add-ons    (9: database, auth, jobs, store, mcp, logging, telemetry, bots, shadcn-ui)
│   └── Generator  (template engine + file system)
│
├── generate       ← Scaffold code from schemas
│   ├── feature    (with optional Prisma schema provider)
│   ├── controller (inside a feature)
│   ├── procedure  (inside a feature)
│   ├── docs       (OpenAPI spec generation)
│   ├── schema     (client TypeScript schema)
│   └── caller     (OpenAPI → typed IgniterCaller)
│
└── dev            ← Watch mode with TUI
    ├── Watcher    (chokidar — router + features directory)
    ├── Generator  (schema + OpenAPI on change)
    └── TUI        (Ink-based split-pane terminal UI)
```

### Core Systems

| System                        | Purpose                                                                                                    |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Template Engine**           | Handlebars-based rendering with custom helpers (`includes`, `isEmpty`, `camelCase`, `filterPlugins`, etc.) |
| **Starter Registry**          | Extensible registry of project starters (each with templates, env vars, dependencies)                      |
| **Add-on Registry**           | Extensible registry of add-ons (each with templates, dependencies, Docker config, env vars)                |
| **Schema Provider Registry**  | Extensible registry of schema providers (currently: Prisma) for schema-aware scaffolding                   |
| **Package Manager Detection** | Auto-detects npm, yarn, pnpm, or bun from `npm_config_user_agent`                                          |
| **Framework Detection**       | Auto-detects Next.js or TanStack Start when installing into existing projects                              |

***

## Quick Start

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install -g @igniter-js/cli
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add -g @igniter-js/cli
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn global add @igniter-js/cli
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add -g @igniter-js/cli
    ```
  </Tab>
</Tabs>

```bash
# Create a Next.js project with database + auth in 60 seconds
igniter init my-app \
  --template nextjs \
  --add-ons database,auth \
  --database postgresql

cd my-app

# Generate a Prisma-backed feature
igniter generate feature users --schema prisma:User

# Start dev mode — schema + docs regenerate on file change
igniter dev
```

***

## Real-World Use Cases

| Scenario                     | What the CLI Provides                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------ |
| **New SaaS project**         | Next.js starter + database (Prisma/PostgreSQL) + auth (Better Auth) + jobs — all in one `init`   |
| **Microservice API**         | Express starter + logging + telemetry + MCP server for AI agent integration                      |
| **Existing Next.js app**     | `igniter init . --mode install` — adds Igniter.js without overwriting your code                  |
| **Schema-first development** | `igniter generate feature` from Prisma models — controllers and procedures generated from schema |
| **API client generation**    | `igniter generate caller` from any OpenAPI spec → typed, validated caller in seconds             |
| **Team onboarding**          | One `igniter init` command replaces pages of setup docs; new devs are productive in minutes      |

***

## Next Steps

<Cards>
  <Card title="Installation" description="Global and per-project installation — runtime requirements and TypeScript setup." href="/docs/cli/installation" />

  <Card title="Quick Start" description="Create your first project in 2 minutes — starter, add-ons, and feature scaffolding." href="/docs/cli/quick-start" />

  <Card title="Commands" description="Deep dive into init, generate, and dev — every flag, option, and workflow." href="/docs/cli/commands/init" />

  <Card title="Starters" description="Compare all 6 starters — frameworks, runtimes, and configuration details." href="/docs/cli/starters" />

  <Card title="Add-ons" description="All 9 add-ons — inline option notation, templates, and environment variables." href="/docs/cli/add-ons" />
</Cards>


---

# Installation

> Install the Igniter.js CLI globally or per-project. Node.js 18.17+ required. Supports npm, pnpm, yarn, and bun.
URL: https://igniterjs.com/docs/cli/installation

## Installation

The CLI can be installed **globally** (recommended) or run **on-demand** with your package manager's executor. It requires **Node.js 18.17 or later**.

<Callout type="warn">
  The CLI uses `commander` for argument parsing, `@clack/prompts` for interactive prompts, and `chokidar` for file watching. These are bundled — no external system dependencies.
</Callout>

***

## Global Installation

Install once, use everywhere:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install -g @igniter-js/cli
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add -g @igniter-js/cli
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn global add @igniter-js/cli
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add -g @igniter-js/cli
    ```
  </Tab>
</Tabs>

Verify the installation:

```bash
igniter --help
```

You should see the top-level help output listing `init`, `generate`, and `dev` commands.

***

## Run Without Installing

You can run the CLI on-demand without global installation:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest --help
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest --help
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest --help
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest --help
    ```
  </Tab>
</Tabs>

<Callout type="info">
  Adding `@latest` ensures you always get the most recent version. For CI/CD pipelines, pin to a specific version: `@igniter-js/cli@0.0.1`.
</Callout>

***

## Per-Project Installation

If you prefer to install the CLI as a dev dependency in a specific project:

```bash
npm install -D @igniter-js/cli
```

Then use it via `npx`:

```bash
npx igniter init my-app
```

Or add it to your `package.json` scripts:

```json
{
  "scripts": {
    "igniter:init": "igniter init",
    "igniter:generate": "igniter generate",
    "igniter:dev": "igniter dev"
  }
}
```

***

## Requirements

| Requirement    | Minimum Version | Notes                                                        |
| -------------- | --------------- | ------------------------------------------------------------ |
| **Node.js**    | 18.17+          | Required for `fetch`, native `fs/promises`, and ESM support  |
| **TypeScript** | 5.3+            | For generated code type inference (optional but recommended) |

<Callout type="info">
  The CLI itself is built with TypeScript and compiled with `tsup`. Generated code uses TypeScript features available in 5.3+ — if your project uses an older version, update your `tsconfig.json`.
</Callout>

***

## Next Steps

<Cards>
  <Card title="Quick Start" description="Create your first project in 2 minutes — starter, add-ons, and first feature." href="/docs/cli/quick-start" />

  <Card title="Commands" description="Deep dive into init, generate, and dev — every flag, option, and workflow." href="/docs/cli/commands/init" />
</Cards>


---

# Quick Start

> Create a full-stack Igniter.js project in 2 minutes. Next.js starter, PostgreSQL database with Prisma, Better Auth, and your first generated feature — copy-paste ready.
URL: https://igniterjs.com/docs/cli/quick-start

## Quick Start

This guide walks you from zero to a running Igniter.js project in under two minutes. You'll create a Next.js project with a PostgreSQL database, authentication, and a schema-generated feature — all from the terminal.

<Steps>
  <Step>
    ### Install the CLI

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        npm install -g @igniter-js/cli
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add -g @igniter-js/cli
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn global add @igniter-js/cli
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add -g @igniter-js/cli
        ```
      </Tab>
    </Tabs>

    Verify it works:

    ```bash
    igniter --help
    # Usage: igniter [options] [command]
    # Commands:
    #   init        Create a new Igniter.js project with interactive setup
    #   generate    Scaffold new features or generate client schema
    #   dev         Start development mode with automatic schema and docs regeneration
    ```
  </Step>

  <Step>
    ### Create a Project

    The `init` command creates a new project. You can answer interactive prompts or pass flags directly:

    ```bash
    igniter init my-saas \
      --template nextjs \
      --add-ons database,auth \
      --database postgresql
    ```

    This command:

    * Creates `my-saas/` with a Next.js starter
    * Configures Prisma with a PostgreSQL provider
    * Wires Better Auth with default plugins
    * Sets up Docker Compose (PostgreSQL container)
    * Installs dependencies automatically
    * Initializes a Git repository

    <Callout type="info">
      **What happens under the hood:** The CLI clones the Next.js starter template, applies add-on templates (database configuration, auth setup), merges environment variables into `.env`, adds Docker services to `docker-compose.yml`, updates `package.json` dependencies, and runs post-install hooks.
    </Callout>

    ```bash
    cd my-saas
    ```
  </Step>

  <Step>
    ### Explore the Project Structure

    Your project now has a complete Igniter.js structure:

    <Files>
      <Folder name="my-saas" defaultOpen>
        <Folder name="src">
          <Folder name="features">
            <Folder name="example">
              <File name="controllers/example.controller.ts" />

              <File name="procedures/example.procedure.ts" />

              <File name="example.interfaces.ts" />
            </Folder>
          </Folder>

          <File name="igniter.router.ts" />

          <File name="igniter.client.ts" />

          <File name="igniter.context.ts" />

          <File name="igniter.schema.ts" />

          <File name="igniter.config.ts" />
        </Folder>

        <File name="prisma/schema.prisma" />

        <File name="docker-compose.yml" />

        <File name=".env" />

        <File name="package.json" />
      </Folder>
    </Files>

    The `example` feature was scaffolded automatically. Every feature follows the same pattern: controllers (HTTP routes), procedures (business logic), and interfaces (TypeScript types).
  </Step>

  <Step>
    ### Generate a Feature from Your Database Schema

    Define a model in `prisma/schema.prisma`:

    ```prisma
    model User {
      id        String   @id @default(cuid())
      name      String
      email     String   @unique
      createdAt DateTime @default(now())
      updatedAt DateTime @updatedAt
    }
    ```

    Then generate the feature:

    ```bash
    igniter generate feature users --schema prisma:User
    ```

    This produces a complete feature with:

    * **Controller** — CRUD routes (`GET /users`, `POST /users`, etc.)
    * **Procedure** — type-safe business logic with Prisma queries
    * **Interfaces** — Zod-validated input/output types derived from the schema

    <Callout type="info">
      The `--schema` flag uses the **Prisma schema provider**. It reads your `schema.prisma`, extracts the model definition, and generates controllers with typed Zod schemas matching your column types.
    </Callout>
  </Step>

  <Step>
    ### Start Development Mode

    Run `igniter dev` to start your development server with automatic schema regeneration:

    ```bash
    igniter dev --cmd "pnpm dev"
    ```

    The dev command:

    * Starts your app's dev server via the `--cmd` flag
    * Watches `src/igniter.router.ts` and `src/features/` for changes
    * Regenerates `src/igniter.schema.ts` (client schema) on every change
    * Regenerates `src/docs/` (OpenAPI spec) on every change
    * Displays a split-pane TUI with Igniter logs and app logs

    <Callout type="info">
      The file watcher uses a **300ms debounce** to avoid rapid regeneration. It ignores `node_modules`, `.git`, `dist`, `.next`, `.turbo`, `.cache`, and test files.
    </Callout>
  </Step>

  <Step>
    ### Register Your Feature in the Router

    Open `src/igniter.router.ts` and register the generated controller:

    ```typescript
    import { IgniterRouter } from '@igniter-js/core';
    import { UsersController } from './features/users/controllers/users.controller';

    export const igniterRouter = IgniterRouter.create()
      .addController(UsersController)
      .build();
    ```

    The dev watcher detects the change and regenerates the schema automatically. Your new routes are now typed and available in the client.
  </Step>
</Steps>

***

## ✅ Success Checkpoint

You now have a project that:

* Runs on **Next.js** with the Igniter.js framework
* Has a **PostgreSQL database** configured via Prisma
* Includes **Better Auth** for authentication
* Has a **schema-generated feature** (users) with CRUD routes
* Uses **dev mode** to auto-regenerate the client schema and OpenAPI docs
* Can be started with a single command

***

## What You Can Do Next

```bash
# Add more add-ons to an existing project
igniter init . --mode install --add-ons jobs,logging,telemetry

# Generate a caller from an external OpenAPI spec
igniter generate caller --name stripe --url https://api.stripe.com/openapi.json

# Generate only the OpenAPI docs
igniter generate docs

# Generate only the client schema
igniter generate schema

# Scaffold a new controller inside a feature
igniter generate controller profile --feature users

# Scaffold a new procedure
igniter generate procedure send-welcome-email --feature users
```

***

## Next Steps

<Cards>
  <Card title="Commands Reference" description="Deep dive into every command — init, generate, dev — with all flags and options." href="/docs/cli/commands/init" />

  <Card title="Starters" description="Compare all 6 starters and pick the right one for your stack." href="/docs/cli/starters" />

  <Card title="Add-ons" description="Learn inline option notation and explore all 9 add-ons in detail." href="/docs/cli/add-ons" />

  <Card title="Real-World Scenarios" description="Production-ready patterns: SaaS, microservices, existing projects, and more." href="/docs/cli/real-world" />
</Cards>


---

# Real-World Scenarios

> Production-ready CLI patterns. SaaS startup, microservices, existing projects, CI/CD pipelines, team onboarding, and monorepos — with complete copy-paste commands.
URL: https://igniterjs.com/docs/cli/real-world

## Real-World Scenarios

This page shows the CLI in action across common production scenarios. Every command is copy-paste ready and grounded in the actual implementation.

***

## Scenario 1: Full-Stack SaaS Startup

**Goal:** Create a Next.js SaaS with PostgreSQL, authentication, background jobs, logging, and telemetry — all from a single command.

```bash
igniter init my-saas \
  --template nextjs \
  --add-ons "database:prisma:postgresql,auth:better-auth:email+magic-link+passkey,jobs,logging,telemetry" \
  --pm pnpm
```

**What you get:**

* Next.js 15 with App Router, Tailwind CSS, and Turbopack
* Prisma ORM with PostgreSQL (Docker container auto-configured)
* Better Auth with email, magic link, and passkey plugins
* BullMQ job queue backed by Redis (Docker container auto-configured)
* Pino structured logger with console transport
* OpenTelemetry tracing wiring

**Next steps:**

```bash
cd my-saas
igniter dev --cmd "pnpm dev"

# Generate your first feature from the database
igniter generate feature users --schema prisma:User

# In another terminal, start a worker
pnpm jobs:worker
```

***

## Scenario 2: Microservices Architecture

**Goal:** Create three independent services — an API gateway (Express), a worker service (Bun), and a Deno edge function — all using Igniter.js.

### API Gateway (Express)

```bash
igniter init api-gateway \
  --template express-rest-api \
  --add-ons logging,telemetry \
  --no-docker
```

### Worker Service (Bun)

```bash
igniter init worker-service \
  --template bun-rest-api \
  --add-ons "database:prisma:postgresql,jobs,logging" \
  --pm bun
```

### Edge Function (Deno)

```bash
igniter init edge-functions \
  --template deno-rest-api \
  --add-ons logging \
  --no-docker --no-git
```

**Shared patterns:**

* All services use `logging` for structured output
* The worker service shares the same database but has its own `igniter.router.ts`
* Each service can generate callers from the others' OpenAPI specs

```bash
# Generate a typed caller from the API gateway
cd worker-service
igniter generate caller --name gateway --path ../api-gateway/src/docs/openapi.json
```

***

## Scenario 3: Adding Igniter.js to an Existing Project

**Goal:** Integrate Igniter.js into an existing Next.js project without overwriting any code.

```bash
cd my-existing-nextjs-app

# Install mode — detects Next.js framework automatically
igniter init . --mode install \
  --add-ons "database:prisma:postgresql,auth:better-auth:email" \
  --pm pnpm
```

**What happens:**

* Framework is auto-detected from `next.config.ts`
* Templates are applied but don't overwrite existing files
* Dependencies are merged into `package.json`
* Environment variables are appended to `.env`
* Docker Compose is updated (if `--no-docker` is not passed)

<Callout type="warn">
  Install mode does **not** run `create-next-app`. It layers Igniter.js on top of your existing project structure.
</Callout>

***

## Scenario 4: OpenAPI-First Development

**Goal:** Generate a fully typed Igniter Caller from a third-party API's OpenAPI spec.

```bash
# From a remote URL
igniter generate caller --name stripe --url https://api.stripe.com/openapi.json

# From a local file
igniter generate caller --name internal --path ./docs/internal-api.json

# Multiple callers
igniter generate caller --name sendgrid --url https://api.sendgrid.com/openapi.json
igniter generate caller --name github --url https://api.github.com/openapi.json
```

**Generated structure:**

```
src/callers/
├── api.stripe.com/
│   ├── schema.ts     ← Zod-validated request/response types
│   └── index.ts      ← Preconfigured Stripe caller
├── api.sendgrid.com/
│   ├── schema.ts
│   └── index.ts
└── api.github.com/
    ├── schema.ts
    └── index.ts
```

**Usage in your code:**

```typescript
import { stripeCaller } from '@/callers/api.stripe.com';

const customer = await stripeCaller.post('/v1/customers', {
  body: { email: 'user@example.com', name: 'John Doe' }
});
// Fully typed — customer is inferred from the OpenAPI spec
```

***

## Scenario 5: CI/CD Pipeline

**Goal:** Automate project creation and schema generation in CI/CD.

### GitHub Actions

```yaml
name: Generate Client Schema

on:
  push:
    paths:
      - 'src/features/**'
      - 'src/igniter.router.ts'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - name: Install CLI
        run: pnpm add -g @igniter-js/cli@0.0.1

      - name: Install dependencies
        run: pnpm install

      - name: Generate schema and docs
        run: |
          igniter generate schema
          igniter generate docs

      - name: Check for changes
        run: |
          if [ -n "$(git status --porcelain)" ]; then
            echo "Schema or docs changed. Commit the updates."
            exit 1
          fi
```

### Dockerfile

```dockerfile
FROM node:20-alpine AS builder
RUN npm install -g @igniter-js/cli@0.0.1
WORKDIR /app
COPY . .
RUN igniter generate schema
RUN igniter generate docs
RUN pnpm build

FROM node:20-alpine AS runner
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/src/igniter.schema.ts ./src/igniter.schema.ts
CMD ["pnpm", "start"]
```

***

## Scenario 6: Team Onboarding

**Goal:** Onboard a new developer in under 60 seconds.

```bash
# Step 1: Clone the repo
git clone git@github.com:company/my-saas.git

# Step 2: Run the init command with the team's standard config
cd my-saas
igniter init . --mode install --add-ons "database:prisma:postgresql,auth:better-auth:email+magic-link"

# Step 3: Start dev mode
igniter dev --cmd "pnpm dev"

# Done — the new dev has a running project with:
# ✅ Database configured (Prisma + PostgreSQL Docker)
# ✅ Auth wired (Better Auth)
# ✅ Schema + docs regenerated
# ✅ Dev server running
```

**No manual setup required:**

* No `.env` copy-pasting (handled by add-ons)
* No `docker-compose.yml` configuration (handled by database add-on)
* No auth wiring (handled by auth add-on)
* No schema bootstrapping (handled by dev mode)

***

## Scenario 7: Monorepo with Multiple Packages

**Goal:** Use the CLI in a Turborepo monorepo with multiple Igniter.js apps.

```
my-monorepo/
├── apps/
│   ├── web/          ← Next.js (Igniter.js)
│   ├── api/          ← Express (Igniter.js)
│   └── worker/       ← Bun (Igniter.js)
├── packages/
│   ├── shared-types/  ← Shared TypeScript types
│   └── ui/           ← Shared React components
└── turbo.json
```

```bash
# Initialize each app individually
cd apps/web
igniter init . --mode install --add-ons logging

cd ../api
igniter init . --mode install --add-ons "database:prisma:postgresql,logging,telemetry"

cd ../worker
igniter init . --mode install --add-ons "jobs,logging"

# Generate callers from the API for the web app
cd apps/web
igniter generate caller --name api --path ../api/src/docs/openapi.json
```

***

## Next Steps

<Cards>
  <Card title="API Reference" description="Complete reference for every CLI flag, option, and subcommand." href="/docs/cli/api-reference" />

  <Card title="Best Practices" description="Do's and don'ts for production CLI workflows." href="/docs/cli/best-practices" />

  <Card title="Troubleshooting" description="Common issues and solutions for init, generate, and dev." href="/docs/cli/troubleshooting" />
</Cards>


---

# Starters

> All 6 Igniter.js starters compared — Next.js, TanStack Start, Express, Bun, Deno. Frameworks, runtimes, env vars, and templates.
URL: https://igniterjs.com/docs/cli/starters

## Starters

Starters are project templates that bootstrap a working Igniter.js application. Each starter targets a specific framework and runtime, and includes the core Igniter.js wiring (router, client, context) plus a scaffolded example feature.

<Callout type="info">
  Starters use `create-next-app`, `create-tanstack-app`, or framework equivalents to initialize the project, then layer Igniter.js templates on top. This means you get the framework's standard project structure plus Igniter.js integration.
</Callout>

***

## Comparison

| Starter              | Framework      | Runtime | Type        | App Router |
| -------------------- | -------------- | ------- | ----------- | ---------- |
| **nextjs**           | Next.js 15     | Node.js | Full-stack  | Yes        |
| **tanstack-start**   | TanStack Start | Node.js | Full-stack  | Yes        |
| **express-rest-api** | Express        | Node.js | Backend API | N/A        |
| **bun-rest-api**     | Bun            | Bun     | Backend API | N/A        |
| **bun-react-app**    | Bun + React    | Bun     | Full-stack  | N/A        |
| **deno-rest-api**    | Deno           | Deno    | Backend API | N/A        |

***

## `nextjs`

The most full-featured starter. Uses `create-next-app` with TypeScript, ESLint, Tailwind CSS, App Router, Turbopack, and `src/` directory.

**Init command:** `npx create-next-app@latest`

**Dependencies:** `@igniter-js/core` (latest)

### Generated Files

| Template                            | Output                               |
| ----------------------------------- | ------------------------------------ |
| `starters/nextjs/route-handler.hbs` | `src/app/api/v1/[[...all]]/route.ts` |
| `starters/igniter.router.hbs`       | `src/igniter.router.ts`              |
| `starters/igniter.client.hbs`       | `src/igniter.client.ts`              |
| `starters/igniter.context.hbs`      | `src/igniter.context.ts`             |
| `starters/igniter.hbs`              | `src/igniter.ts`                     |
| `scaffold/example-feature/*.hbs`    | `src/features/example/`              |
| `starters/nextjs/tsconfig.hbs`      | `tsconfig.json`                      |
| `starters/open-api.hbs`             | `src/docs/openapi.json`              |

### Environment Variables

| Variable                            | Default                  | Description               |
| ----------------------------------- | ------------------------ | ------------------------- |
| `IGNITER_APP_NAME`                  | `Igniter App`            | Application name          |
| `IGNITER_APP_SECRET`                | `my-secret-key`          | Application secret        |
| `IGNITER_API_URL`                   | `http://localhost:3000/` | Server-side API URL       |
| `IGNITER_API_BASE_PATH`             | `/api/v1`                | API base path             |
| `NEXT_PUBLIC_IGNITER_API_URL`       | `http://localhost:3000/` | Client-side API URL       |
| `NEXT_PUBLIC_IGNITER_API_BASE_PATH` | `/api/v1`                | Client-side API base path |

### Example

```bash
igniter init my-app --template nextjs
```

***

## `tanstack-start`

Full-stack starter using TanStack Start with a similar structure to the Next.js starter.

**Dependencies:** `@igniter-js/core` (latest)

### Environment Variables

| Variable                          | Default                  | Description               |
| --------------------------------- | ------------------------ | ------------------------- |
| `IGNITER_APP_NAME`                | `Igniter App`            | Application name          |
| `IGNITER_APP_SECRET`              | `my-secret-key`          | Application secret        |
| `IGNITER_API_URL`                 | `http://localhost:3000/` | Server-side API URL       |
| `IGNITER_API_BASE_PATH`           | `/api/v1`                | API base path             |
| `REACT_APP_IGNITER_API_URL`       | `http://localhost:3000/` | Client-side API URL       |
| `REACT_APP_IGNITER_API_BASE_PATH` | `/api/v1`                | Client-side API base path |

### Example

```bash
igniter init my-app --template tanstack-start
```

***

## `express-rest-api`

A backend-only starter using Express.js. Includes the core Igniter.js router, client, and context — without any frontend framework.

**Dependencies:** `@igniter-js/core` (latest)

### Environment Variables

| Variable                | Default | Description        |
| ----------------------- | ------- | ------------------ |
| `IGNITER_APP_NAME`      | —       | Application name   |
| `IGNITER_APP_SECRET`    | —       | Application secret |
| `IGNITER_API_URL`       | —       | API URL            |
| `IGNITER_API_BASE_PATH` | —       | API base path      |

### Example

```bash
igniter init my-api --template express-rest-api
```

***

## `bun-rest-api`

A backend-only starter targeting the **Bun** runtime. Uses Bun's native HTTP server with Igniter.js integration.

**Dependencies:** `@igniter-js/core` (latest)

### Environment Variables

| Variable                | Default | Description        |
| ----------------------- | ------- | ------------------ |
| `IGNITER_APP_NAME`      | —       | Application name   |
| `IGNITER_APP_SECRET`    | —       | Application secret |
| `IGNITER_API_URL`       | —       | API URL            |
| `IGNITER_API_BASE_PATH` | —       | API base path      |

### Example

```bash
igniter init my-bun-api --template bun-rest-api
```

***

## `bun-react-app`

A full-stack starter using **Bun + React**. Combines Bun's server with a React frontend.

**Dependencies:** `@igniter-js/core` (latest)

### Environment Variables

| Variable                | Default | Description        |
| ----------------------- | ------- | ------------------ |
| `IGNITER_APP_NAME`      | —       | Application name   |
| `IGNITER_APP_SECRET`    | —       | Application secret |
| `IGNITER_API_URL`       | —       | API URL            |
| `IGNITER_API_BASE_PATH` | —       | API base path      |

### Example

```bash
igniter init my-bun-react --template bun-react-app
```

***

## `deno-rest-api`

A backend-only starter targeting the **Deno** runtime. Uses Deno's native HTTP server with Igniter.js integration.

**Dependencies:** `@igniter-js/core` (latest)

### Environment Variables

| Variable                | Default | Description        |
| ----------------------- | ------- | ------------------ |
| `IGNITER_APP_NAME`      | —       | Application name   |
| `IGNITER_APP_SECRET`    | —       | Application secret |
| `IGNITER_API_URL`       | —       | API URL            |
| `IGNITER_API_BASE_PATH` | —       | API base path      |

### Example

```bash
igniter init my-deno-api --template deno-rest-api
```

***

## Starter Architecture

All starters extend `BaseStarter` and implement a common interface:

```typescript
interface Starter {
  id: string;           // CLI identifier (e.g., 'nextjs')
  name: string;         // Display name
  description: string;  // Short description
  hint: string;         // Category hint for prompts
  repository: string;   // Source repository name
  templates: Template[]; // Handlebars templates to apply
  dependencies: Dep[];  // Package dependencies
  envVars: EnvVar[];    // Environment variables
  install(dir, config): Promise<void>;  // Installation logic
}
```

New starters can be added by extending `BaseStarter`, implementing the `install` method, and registering with the `StarterRegistry`.

***

## Next Steps

<Cards>
  <Card title="Add-ons" description="Layer database, auth, jobs, and more on top of any starter." href="/docs/cli/add-ons" />

  <Card title="Real-World Scenarios" description="See which starter + add-on combinations work best for common use cases." href="/docs/cli/real-world" />

  <Card title="init Command" description="Full reference for the init command — modes, flags, and inline options." href="/docs/cli/commands/init" />
</Cards>


---

# Troubleshooting

> Common CLI errors and their solutions. Init failures, schema generation errors, file watcher issues, port conflicts, and framework detection gotchas.
URL: https://igniterjs.com/docs/cli/troubleshooting

## Troubleshooting

Solutions for common issues you may encounter while using `@igniter-js/cli`.

***

## Init Errors

### "Could not locate the CLI templates directory"

**Symptom:** The CLI exits with a template resolution error.

**Cause:** The Handlebars template engine cannot find the `templates/` directory. This can happen if the CLI is installed in an unusual location or if the package is corrupted.

**Solution:**

1. Verify the CLI installation:

   ```bash
   igniter --version
   # Should print: 0.0.1
   ```

2. Reinstall the CLI:

   ```bash
   npm uninstall -g @igniter-js/cli
   npm install -g @igniter-js/cli
   ```

3. If using `npx`, ensure the cache is fresh:

   ```bash
   npx @igniter-js/cli@0.0.1 init my-app
   ```

***

### "Starter not found"

**Symptom:** `p.log.error("Starter not found")` is printed during init.

**Cause:** The `--template` value doesn't match any registered starter.

**Solution:** Use one of the valid template values:

```bash
# ✅ Valid values
igniter init --template nextjs
igniter init --template tanstack-start
igniter init --template express-rest-api
igniter init --template bun-rest-api
igniter init --template bun-react-app
igniter init --template deno-rest-api

# ❌ Invalid
igniter init --template react
igniter init --template vue
```

***

### "Project initialization failed"

**Symptom:** The init process fails with a generic error message.

**Common causes:**

1. **Network issues** — `create-next-app` or framework CLI cannot download templates.
2. **Permission issues** — Cannot write to the target directory.
3. **Name conflicts** — A directory with the project name already exists.

**Solutions:**

* Check your internet connection
* Ensure you have write permissions in the target directory
* Use a unique project name or pass `--mode install` for existing directories

***

## Generate Errors

### "No registered schema provider can handle 'prisma:X'"

**Symptom:** Feature generation fails with a schema provider error.

**Cause:** The schema provider isn't registered, or the schema file wasn't found.

**Solutions:**

1. Ensure a `prisma/schema.prisma` file exists in your project:

   ```bash
   ls prisma/schema.prisma
   ```

2. If using a custom schema path, use `--schema-path`:

   ```bash
   igniter generate feature users --schema prisma:User --schema-path ./custom/schema.prisma
   ```

3. Verify the model name exists in your schema:

   ```prisma
   // prisma/schema.prisma
   model User {  // ← This name must match --schema prisma:User
     id String @id
   }
   ```

***

### "Feature 'X' already exists"

**Symptom:** `Feature 'users' already exists at src/features/users.`

**Cause:** A feature with the same name already exists.

**Solutions:**

1. Use a different feature name:

   ```bash
   igniter generate feature user-management --schema prisma:User
   ```

2. Or scaffold individual controllers/procedures inside the existing feature:

   ```bash
   igniter generate controller profile --feature users
   igniter generate procedure send-welcome --feature users
   ```

***

### OpenAPI Generation Fails

**Symptom:** `igniter generate docs` or `igniter generate caller` fails.

**Common causes:**

1. Router file not found at the expected path
2. OpenAPI document is not valid 3.x
3. Invalid YAML syntax in the OpenAPI file

**Solutions:**

* Verify the router path:

  ```bash
  ls src/igniter.router.ts
  ```

* For `caller`, ensure the OpenAPI document is 3.x (not Swagger 2.0):

  ```bash
  # Check the openapi version in the document
  cat openapi.json | grep '"openapi"'
  # Should be "3.x.x"
  ```

* Validate JSON/YAML syntax:

  ```bash
  # JSON
  cat openapi.json | python -m json.tool > /dev/null

  # YAML
  cat openapi.yaml | python -c "import yaml; yaml.safe_load(open('openapi.yaml'))"
  ```

***

## Dev Errors

### "Router file not found"

**Symptom:** Dev mode exits with `Router file not found: /path/to/igniter.router.ts`.

**Cause:** The router file doesn't exist at the expected location.

**Solution:** Specify the correct router path:

```bash
igniter dev --router ./src/custom/path/igniter.router.ts
```

***

### File Watcher Not Detecting Changes

**Symptom:** Schema and docs don't regenerate when files change.

**Possible causes:**

1. **File in ignored directory** — Files in `node_modules/`, `.git/`, `dist/`, `.next/`, `.turbo/`, `.cache/` are ignored
2. **Test files are ignored** — `*.test.ts` and `*.spec.ts` files are ignored
3. **Debounce delay** — There's a 300ms debounce; changes within 300ms are batched

**Solutions:**

* Move source files outside ignored directories
* Wait 300ms after saving before checking for regeneration
* Check the Igniter Logs panel in the TUI for file change events

***

### "Failed to regenerate" Errors

**Symptom:** Dev mode shows red error logs for schema or doc regeneration.

**Common causes:**

1. TypeScript compilation errors in the router or features
2. Circular imports in feature modules
3. Invalid Zod schemas in procedure definitions

**Solutions:**

* Check your application logs for compilation errors:

  ```bash
  pnpm dev
  # Look for TypeScript errors in the output
  ```

* Ensure procedures export valid Zod schemas:

  ```typescript
  // ✅ Valid
  export const createUserProcedure = IgniterProcedure.create()
    .input(z.object({ name: z.string() }))
    .handler(async ({ input }) => { ... });

  // ❌ Invalid — schema type error causes regeneration failure
  export const brokenProcedure = IgniterProcedure.create()
    .input(z.object({ name: z.nonexistent() }))  // This method doesn't exist
    .handler(async ({ input }) => { ... });
  ```

***

## Port Conflicts

### Docker Port Already in Use

**Symptom:** Docker setup fails because port 5432 or 6379 is in use.

**Cause:** Another service is using the port that Docker Compose needs.

**Solutions:**

1. Check what's using the port:

   ```bash
   # macOS/Linux
   lsof -i :5432
   lsof -i :6379

   # Or
   sudo lsof -i -P | grep LISTEN
   ```

2. Stop the conflicting process:

   ```bash
   kill -9 <PID>
   ```

3. Or skip Docker setup entirely:

   ```bash
   igniter init my-app --no-docker
   ```

***

## Package Manager Issues

### Wrong Package Manager Detected

**Symptom:** The CLI uses `npm` but you expected `pnpm`.

**Cause:** `npm_config_user_agent` is not set or is set to a different package manager.

**Solution:** Always use the `--pm` flag for explicit control:

```bash
igniter init my-app --template nextjs --pm pnpm
```

***

## Permission Errors

### "EACCES: permission denied"

**Symptom:** The CLI cannot write files to the target directory.

**Solutions:**

1. Check directory permissions:

   ```bash
   ls -la /path/to/target
   ```

2. Run with appropriate permissions or change directory ownership:

   ```bash
   sudo chown -R $(whoami) /path/to/target
   ```

3. For global installation issues, use a Node.js version manager (nvm, fnm, volta) instead of system Node.js.

***

## Still Having Issues?

If you encounter an error not covered here:

1. Run the command with verbose output
2. Check the Igniter Logs panel in `igniter dev` for detailed error messages
3. Verify the error against the implementation in `packages/cli/src/`
4. Open an issue on the Igniter.js repository

***

## Next Steps

<Cards>
  <Card title="Best Practices" description="Avoid common issues with production-ready patterns." href="/docs/cli/best-practices" />

  <Card title="API Reference" description="Verify flag behavior and defaults against the complete reference." href="/docs/cli/api-reference" />

  <Card title="Real-World Scenarios" description="See working examples of all CLI features in production contexts." href="/docs/cli/real-world" />
</Cards>


---

# Adapters

> Choose the right storage adapter for your environment. Covers Node FS, Bun FS, Redis, S3, Mock, and building custom adapters.
URL: https://igniterjs.com/docs/collections/adapters

## Adapters

Adapters abstract storage operations behind a unified interface. Switch from local filesystem to Redis or S3 without changing a single line of collection code.

***

## Available Adapters

| Adapter                          | Runtime     | Storage          | Use Case                              |
| -------------------------------- | ----------- | ---------------- | ------------------------------------- |
| **NodeFsAdapter**                | Node.js 18+ | Local filesystem | Server-side apps, local dev           |
| **BunFsAdapter**                 | Bun 1.0+    | Local filesystem | Bun-native apps, maximum perf         |
| **BunRedisAdapter**              | Bun 1.0+    | Redis            | Distributed systems, multi-process    |
| **BunS3Adapter**                 | Bun 1.0+    | AWS S3           | Production deployment, object storage |
| **IgniterCollectionMockAdapter** | Any         | In-memory Map    | Testing and CI                        |

***

## NodeFsAdapter

The default adapter for Node.js environments. Uses `node:fs/promises` and `fast-glob`.

```typescript
import { NodeFsAdapter } from '@igniter-js/collections/adapters';

const adapter = new NodeFsAdapter();

const docs = IgniterCollections.create()
  .withAdapter(adapter)
  .withBasePath(process.cwd())
  .addCollection(Posts)
  .build();
```

**Features:**

* File watching via `node:fs.watch`
* Recursive directory creation
* Glob-based file listing via `fast-glob`
* Standard POSIX file operations

***

## BunFsAdapter

Optimized for Bun runtime. Uses `Bun.file`, `Bun.write`, and `Bun.Glob` for maximum performance.

```typescript
import { BunFsAdapter } from '@igniter-js/collections/adapters';

const adapter = new BunFsAdapter();

const docs = IgniterCollections.create()
  .withAdapter(adapter)
  .withBasePath(process.cwd())
  .addCollection(Posts)
  .build();
```

<Callout type="warn">
  **Bun-only.** This adapter uses Bun-native APIs and will throw if used in Node.js.
</Callout>

***

## BunRedisAdapter

Stores documents in Redis for distributed access. Supports key prefixes for namespacing.

```typescript
import { BunRedisAdapter } from '@igniter-js/collections/adapters';

const adapter = new BunRedisAdapter({
  url: process.env.REDIS_URL!,
  prefix: 'collections:',   // Keys: collections:posts:a1b2c3d4
});

const docs = IgniterCollections.create()
  .withAdapter(adapter)
  .addCollection(Posts)
  .build();
```

**Options:**

| Option   | Type     | Default  | Description                |
| -------- | -------- | -------- | -------------------------- |
| `url`    | `string` | required | Redis connection URL       |
| `prefix` | `string` | `''`     | Key prefix for namespacing |

***

## BunS3Adapter

Stores documents in AWS S3 or any S3-compatible object storage.

```typescript
import { BunS3Adapter } from '@igniter-js/collections/adapters';

const adapter = new BunS3Adapter({
  bucket: 'my-content-bucket',
  region: 'us-east-1',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  // Optional: endpoint for S3-compatible services (MinIO, Cloudflare R2)
  endpoint: 'https://s3.amazonaws.com',
});

const docs = IgniterCollections.create()
  .withAdapter(adapter)
  .addCollection(Posts)
  .build();
```

**Options:**

| Option        | Type                               | Default     | Description                    |
| ------------- | ---------------------------------- | ----------- | ------------------------------ |
| `bucket`      | `string`                           | required    | S3 bucket name                 |
| `region`      | `string`                           | required    | AWS region                     |
| `credentials` | `{ accessKeyId, secretAccessKey }` | required    | AWS credentials                |
| `endpoint`    | `string`                           | AWS default | Custom S3 endpoint (MinIO, R2) |

<Callout type="info">
  **S3-Compatible Storage:** Use the `endpoint` option to connect to MinIO, Cloudflare R2, DigitalOcean Spaces, or any S3-compatible service.
</Callout>

***

## MockAdapter

In-memory adapter for testing. Tracks all operations via `files` and `calls` properties.

```typescript
import { IgniterCollectionMockAdapter } from '@igniter-js/collections/adapters';

const mock = new IgniterCollectionMockAdapter();

const docs = IgniterCollections.create()
  .withAdapter(mock)
  .addCollection(Posts)
  .build();

// Run operations
await docs.posts.create({ data: { title: 'Test', author: 'Test' } });

// Inspect state
console.log(mock.files); // Map<string, string> — path → content
console.log(mock.calls); // Array of method call records
```

***

## Adapter Interface

The `IgniterCollectionAdapter` interface defines six required methods and one optional:

```typescript
interface IgniterCollectionAdapter {
  read(path: string): Promise<string | null>;
  write(path: string, content: string, options?: { ttl?: number }): Promise<void>;
  delete(path: string): Promise<void>;
  list(directory: string, pattern?: string, options?: {
    type?: 'file' | 'directory' | 'both';
  }): Promise<string[]>;
  exists(path: string): Promise<boolean>;
  mkdir(path: string): Promise<void>;
  watch?(path: string, callback: (event, filePath) => void): () => void;
}
```

***

## Building a Custom Adapter

Implement the interface to add any storage backend:

```typescript
import type { IgniterCollectionAdapter } from '@igniter-js/collections';

class PostgresAdapter implements IgniterCollectionAdapter {
  constructor(private db: Database) {}

  async read(path: string): Promise<string | null> {
    const row = await this.db.query(
      'SELECT content FROM documents WHERE path = $1',
      [path]
    );
    return row?.content ?? null;
  }

  async write(path: string, content: string): Promise<void> {
    await this.db.query(
      `INSERT INTO documents (path, content, updated_at)
       VALUES ($1, $2, NOW())
       ON CONFLICT (path) DO UPDATE SET content = $2, updated_at = NOW()`,
      [path, content]
    );
  }

  async delete(path: string): Promise<void> {
    await this.db.query('DELETE FROM documents WHERE path = $1', [path]);
  }

  async list(directory: string, pattern?: string): Promise<string[]> {
    const rows = await this.db.query(
      'SELECT path FROM documents WHERE path LIKE $1',
      [`${directory}%`]
    );
    return rows.map(r => r.path);
  }

  async exists(path: string): Promise<boolean> {
    const row = await this.db.query(
      'SELECT 1 FROM documents WHERE path = $1',
      [path]
    );
    return !!row;
  }

  async mkdir(_path: string): Promise<void> {
    // No-op — PostgreSQL doesn't need directories
  }
}
```

***

## Next Steps

<Cards>
  <Card title="Watcher" description="Auto-discover schemas and views with file watching and hot reload." href="/docs/collections/watcher" />

  <Card title="Advanced" description="Context injection, telemetry, global hooks, and multi-pattern." href="/docs/collections/advanced" />

  <Card title="Troubleshooting" description="Common errors and how to fix them." href="/docs/collections/troubleshooting" />
</Cards>


---

# Advanced Patterns

> Context injection, telemetry, global hooks, multi-pattern files, and custom logging.
URL: https://igniterjs.com/docs/collections/advanced

## Advanced Patterns

Once you've mastered the basics, these patterns unlock the full power of collections for production applications.

***

## Context Injection

Use `withContext()` to inject dependencies into every hook, view data handler, and view action. The factory runs **fresh for every operation** — you always get the latest state.

```typescript
import { IgniterCollections } from '@igniter-js/collections';

interface AppContext {
  db: Database;
  auth: AuthState;
  config: AppConfig;
}

const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withContext(async (): Promise<AppContext> => {
    const [db, auth, config] = await Promise.all([
      Database.connect(),
      getCurrentAuth(),
      loadConfig(),
    ]);
    return { db, auth, config };
  })
  .addCollection(Posts)
  .build();

// Access in hooks
Posts.onCreated(async ({ value, context }) => {
  const { db, auth } = context as AppContext;
  await db.auditLog.create({
    userId: auth.userId,
    action: 'post:created',
    documentId: value.id,
  });
  return value;
});

// Access in views
const DashboardView = IgniterCollectionView.create('dashboard')
  .withData(async ({ manager, context }) => {
    const { auth } = context as AppContext;
    const posts = auth.isAdmin
      ? await manager.posts.findMany()
      : await manager.posts.findMany({ where: { published: true } });
    return { posts };
  })
  .build();
```

<Callout type="info">
  The context factory is called **once per operation**. For batch operations like `findMany`, it's called once. Every hook on a single `create` call shares the same context instance.
</Callout>

***

## Telemetry

Integrate `@igniter-js/telemetry` for observability — track operation duration, error rates, and throughput.

```typescript
import { IgniterTelemetry } from '@igniter-js/telemetry';
import { IgniterCollections } from '@igniter-js/collections';

const telemetry = IgniterTelemetry.create()
  .withAdapter(telemetryAdapter)
  .build();

const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withTelemetry(telemetry)
  .addCollection(Posts)
  .build();

// Collections automatically reports:
// - Operation duration (create, read, update, delete, list)
// - Error rates and error codes
// - Collection name context
// - Document count per operation
```

***

## Global Hooks

Apply hooks to every collection at once — perfect for logging, audit trails, and cross-cutting concerns:

```typescript
const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withGlobalHooks({
    onCreated: async ({ value, collection }) => {
      console.log(`[${collection.definition.name}] Created: ${value.id}`);
      return value;
    },
    onUpdated: async ({ newValue, previousValue, collection }) => {
      console.log(
        `[${collection.definition.name}] Updated: ${newValue.id}`,
        Object.keys(newValue.data).filter(
          k => newValue.data[k] !== previousValue.data[k]
        )
      );
      return newValue;
    },
    onDeleted: async ({ value, collection }) => {
      console.log(`[${collection.definition.name}] Deleted: ${value.id}`);
      return true;
    },
    onRead: async ({ value, collection }) => {
      console.log(`[${collection.definition.name}] Read: ${value.id}`);
      return value;
    },
    onList: async ({ values, collection }) => {
      console.log(`[${collection.definition.name}] Listed: ${values.length} docs`);
      return values;
    },
  })
  .addCollection(Posts)
  .addCollection(Pages)
  .build();
```

<Callout type="info">
  Global hooks run **before** collection-specific hooks. If a global hook returns `false`, the operation cancels and collection hooks never run.
</Callout>

***

## Multi-Pattern Files

Collections supports multiple file patterns per collection. The best-match pattern is used based on available data fields:

```typescript
const Posts = IgniterCollectionModel.create('posts')
  .withPatterns([
    // Organized by year/month when metadata is available
    '.content/posts/{year}/{month}/{id}.mdx',
    // Flat structure as fallback
    '.content/posts/{id}.mdx',
    // Author-organized for team content
    '.content/posts/{author}/{id}.mdx',
  ])
  .withSchema(z.object({
    title: z.string(),
    author: z.string(),
    published: z.boolean(),
  }))
  .build();
```

The system selects the pattern with the most placeholders that can be resolved from the document data. If your data has `year`, `month`, and `author`, the date-based pattern wins.

***

## Custom Logger

Pass a logger for debug output and operation tracking:

```typescript
import type { IgniterLogger } from '@igniter-js/common';

const logger: IgniterLogger = {
  debug: (msg, meta) => console.debug(`[Collections] ${msg}`, meta),
  info: (msg, meta) => console.info(`[Collections] ${msg}`, meta),
  warn: (msg, meta) => console.warn(`[Collections] ${msg}`, meta),
  error: (msg, meta) => console.error(`[Collections] ${msg}`, meta),
};

const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withLogger(logger)
  .addCollection(Posts)
  .build();

// Now you'll see:
// [Collections] Document created: posts/a1b2c3d4 { duration: 12 }
// [Collections] Registered collection from schema: pages
```

***

## Multiple Base Paths

Support content from multiple directories:

```typescript
const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(['.content', '.docs', '.blog']) // Multiple base paths
  .addCollection(Posts)
  .build();
```

The first path in the array is used as the primary base path. Additional paths can be used for pattern-based resolution.

***

## Sub-Collection Depth

Create deeply nested document structures:

```typescript
const Projects = IgniterCollectionModel.create('projects')
  .withPatterns(['.content/projects/{id}.mdx'])
  .withSchema(projectSchema)
  .build();

const Tasks = Projects.collections.create('tasks')
  .withPatterns(['{parent_id}/tasks/{id}.mdx'])
  .withSchema(taskSchema)
  .build();

const Comments = Tasks.collections.create('comments')
  .withPatterns(['{parent_id}/comments/{id}.mdx'])
  .withSchema(commentSchema)
  .build();

// Nested files: .content/projects/proj-1/tasks/task-1/comments/comment-1.mdx
```

***

## Full-Text Search Configuration

Fine-tune the search index with field weights and fuzzy matching:

```typescript
const Posts = IgniterCollectionModel.create('posts')
  .withSchema(z.object({
    title: z.string(),
    description: z.string(),
    body: z.string(),
    tags: z.array(z.string()),
    author: z.string(),
  }))
  .build();

// Search with weighted fields
const results = await docs.posts.findMany({
  where: {
    search: {
      term: 'TypeScript patterns',
      fields: {
        title: { weight: 3, fuzzy: true },
        description: { weight: 1.5 },
        body: { weight: 0.5 },
        tags: { weight: 2 },
      },
      threshold: 0.15,
      fuzzy: false,
    },
  },
});
```

***

## Next Steps

<Cards>
  <Card title="API Reference" description="Complete reference for every builder, manager, and type." href="/docs/collections/api-reference" />

  <Card title="Troubleshooting" description="Common errors, error codes, and debugging strategies." href="/docs/collections/troubleshooting" />

  <Card title="Best Practices" description="Do's and Don'ts, production patterns, and anti-patterns." href="/docs/collections/best-practices" />
</Cards>


---

# API Reference

> Complete reference for IgniterCollectionsBuilder, IgniterCollectionModelBuilder, IgniterCollectionViewBuilder, and all manager types.
URL: https://igniterjs.com/docs/collections/api-reference

## API Reference

Complete reference for all public builders, managers, and types in `@igniter-js/collections`.

***

## `IgniterCollectionsBuilder`

The main entry point. Creates the collections manager.

```typescript
import { IgniterCollections } from '@igniter-js/collections';
```

### Static Methods

| Method                        | Returns                         | Description                   |
| ----------------------------- | ------------------------------- | ----------------------------- |
| `IgniterCollections.create()` | `IgniterCollectionsBuilder<{}>` | Create a new builder instance |

### Builder Methods

| Method                      | Parameters                                                 | Returns                      | Description                        |
| --------------------------- | ---------------------------------------------------------- | ---------------------------- | ---------------------------------- |
| `withAdapter(adapter)`      | `IgniterCollectionAdapter`                                 | Builder                      | Set the storage adapter (required) |
| `withBasePath(path)`        | `string \| string[]`                                       | Builder                      | Set content root path(s)           |
| `addCollection(collection)` | `IgniterCollectionModelDefinition`                         | Builder with added type      | Register a collection              |
| `addView(view)`             | `IgniterCollectionViewDefinition`                          | Builder                      | Register a programmatic view       |
| `withWatcher(paths, opts?)` | `string \| string[], { collections?, views?, autoWatch? }` | Builder                      | Enable auto-discovery              |
| `withContext(factory)`      | `() => unknown \| Promise<unknown>`                        | Builder                      | Inject dependencies into hooks     |
| `withGlobalHooks(hooks)`    | `IgniterCollectionModelHooks`                              | Builder                      | Hooks for all collections          |
| `withTelemetry(telemetry)`  | `IgniterTelemetryManager`                                  | Builder                      | Observability integration          |
| `withLogger(logger)`        | `IgniterLogger`                                            | Builder                      | Custom logger                      |
| `build()`                   | —                                                          | `IIgniterCollectionsManager` | Build the manager                  |

### Returned Manager (`build()`)

The returned manager provides:

```typescript
interface IIgniterCollectionsManager<TCollections> {
  // Dynamic collection access (e.g., docs.posts.create())
  [collectionName]: IIgniterCollectionModel;

  // Subscribe to events
  on(event, handler): IgniterCollectionSubscription;

  // Manual refresh
  refresh(): Promise<void>;

  // Namespaces
  readonly views: IIgniterCollectionViewManager;
  readonly collections: IIgniterCollectionsAccessor;
  readonly watcher: IIgniterCollectionWatcher;
}
```

***

## `IgniterCollectionModelBuilder`

Defines a collection's schema, patterns, hooks, and sub-collections.

```typescript
import { IgniterCollectionModel } from '@igniter-js/collections';
```

### Static Methods

| Method                                | Parameters | Returns | Description                     |
| ------------------------------------- | ---------- | ------- | ------------------------------- |
| `IgniterCollectionModel.create(name)` | `string`   | Builder | Create a new collection builder |

### Builder Methods

| Method                     | Parameters                 | Returns                            | Description                                    |
| -------------------------- | -------------------------- | ---------------------------------- | ---------------------------------------------- |
| `withPatterns(patterns)`   | `string[]`                 | Builder                            | Set file patterns (e.g., `['posts/{id}.mdx']`) |
| `withSchema(schema)`       | `StandardSchemaV1` (Zod)   | Builder with inferred type         | Set frontmatter validation schema              |
| `onCreated(hook)`          | `(ctx) => value \| false`  | Builder                            | Hook before document creation                  |
| `onUpdated(hook)`          | `(ctx) => value \| false`  | Builder                            | Hook before document update                    |
| `onDeleted(hook)`          | `(ctx) => boolean`         | Builder                            | Hook before document deletion                  |
| `onRead(hook)`             | `(ctx) => value \| false`  | Builder                            | Hook after document read                       |
| `onList(hook)`             | `(ctx) => values \| false` | Builder                            | Hook after document listing                    |
| `collections.create(name)` | `string`                   | SubCollectionBuilder               | Create a sub-collection                        |
| `build()`                  | —                          | `IgniterCollectionModelDefinition` | Build the collection definition                |

***

## Collection Manager (`IIgniterCollectionModel`)

The CRUD interface returned by `docs.posts` (or `docs.collections.get('posts')`).

### Methods

| Method               | Parameters                                                        | Returns                              |
| -------------------- | ----------------------------------------------------------------- | ------------------------------------ |
| `create(args)`       | `{ data, id?, select?, exclude? }`                                | `Promise<Document<TSchema>>`         |
| `findUnique(args)`   | `{ where: { id }, select?, exclude? }`                            | `Promise<Document<TSchema> \| null>` |
| `findMany(args?)`    | `{ where?, orderBy?, take?, skip?, select?, exclude?, include? }` | `Promise<Document<TSchema>[]>`       |
| `update(args)`       | `{ where: { id }, data, select?, exclude? }`                      | `Promise<Document<TSchema>>`         |
| `delete(args)`       | `{ where: { id }, select?, exclude? }`                            | `Promise<Document<TSchema>>`         |
| `count(args?)`       | `{ where? }`                                                      | `Promise<number>`                    |
| `on(event, handler)` | `string, (data) => void`                                          | `IgniterCollectionSubscription`      |

***

## `IgniterCollectionViewBuilder`

Defines a declarative view with data hooks and UI component trees.

```typescript
import { IgniterCollectionView } from '@igniter-js/collections';
```

### Static Methods

| Method                               | Parameters | Returns | Description               |
| ------------------------------------ | ---------- | ------- | ------------------------- |
| `IgniterCollectionView.create(name)` | `string`   | Builder | Create a new view builder |

### Builder Methods

| Method                    | Parameters              | Returns                           | Description                     |
| ------------------------- | ----------------------- | --------------------------------- | ------------------------------- |
| `withTitle(title)`        | `string`                | Builder                           | Display title                   |
| `withDescription(desc)`   | `string`                | Builder                           | View description                |
| `withMetadata(meta)`      | `Record<string, any>`   | Builder                           | UI metadata (icon, order, etc.) |
| `withData(hook)`          | `(ctx) => Promise<any>` | Builder                           | Data hook (required)            |
| `withTree(tree)`          | `ViewNode[]`            | Builder                           | Component tree                  |
| `addAction(name, action)` | `string, ViewAction`    | Builder                           | Executable action               |
| `build()`                 | —                       | `IgniterCollectionViewDefinition` | Build view definition           |

***

## `IgniterCollectionsAccessor`

Provides explicit access to collection managers.

```typescript
interface IIgniterCollectionsAccessor<TCollections> {
  get(name): IIgniterCollectionModel;   // Get a collection manager
  list(): Array<{ name, patterns, schema, source }>;  // List all collections
  entries(): Record<string, { name, patterns, schema, source }>;
}
```

***

## `IgniterCollectionWatcher`

Controls the file watcher.

```typescript
interface IIgniterCollectionWatcher {
  start(): Promise<boolean>;  // Start watching
  stop(): void;               // Stop watching
  readonly isWatching: boolean; // Current state
}
```

***

## Where Clause Operators

### Scalar Operators (`IgniterCollectionScalarFilterOperators<T>`)

| Operator     | Type     | Description                    |
| ------------ | -------- | ------------------------------ |
| `equals`     | `T`      | Exact match                    |
| `not`        | `T`      | Not equal                      |
| `in`         | `T[]`    | In array of values             |
| `notIn`      | `T[]`    | Not in array                   |
| `lt`         | `T`      | Less than                      |
| `lte`        | `T`      | Less than or equal             |
| `gt`         | `T`      | Greater than                   |
| `gte`        | `T`      | Greater than or equal          |
| `contains`   | `string` | Substring match (strings only) |
| `startsWith` | `string` | Starts with (strings only)     |
| `endsWith`   | `string` | Ends with (strings only)       |

### Array Operators (`IgniterCollectionArrayFilterOperators<T>`)

| Operator   | Type      | Description                       |
| ---------- | --------- | --------------------------------- |
| `has`      | `T`       | Array contains value              |
| `hasEvery` | `T[]`     | Array contains ALL values         |
| `hasSome`  | `T[]`     | Array contains at least ONE value |
| `isEmpty`  | `boolean` | Array is empty or not             |
| `length`   | `number`  | Array length equals               |

### Search Filter (`IgniterCollectionSearchFilter<T>`)

| Field                   | Type                 | Default       | Description                 |
| ----------------------- | -------------------- | ------------- | --------------------------- |
| `term`                  | `string \| string[]` | required      | Search terms                |
| `fields`                | `SearchFields<T>`    | Common fields | Field weights and fuzziness |
| `threshold`             | `number` (0-1)       | `0.2`         | Minimum score               |
| `fuzzy`                 | `boolean`            | `false`       | Enable fuzzy matching       |
| `includeSubCollections` | `boolean`            | `false`       | Search sub-collections      |

***

## Error Codes

All codes exported from `IGNITER_COLLECTION_ERROR_CODES`:

| Code                               | Description                 |
| ---------------------------------- | --------------------------- |
| `COLLECTION_ADAPTER_REQUIRED`      | Adapter not configured      |
| `COLLECTION_NOT_FOUND`             | Collection not in registry  |
| `COLLECTION_DOCUMENT_NOT_FOUND`    | Document not found at path  |
| `COLLECTION_VALIDATION_ERROR`      | Schema validation failed    |
| `COLLECTION_HOOK_CANCELLED`        | Hook returned false         |
| `COLLECTION_PARSE_ERROR`           | Failed to parse frontmatter |
| `COLLECTION_WRITE_ERROR`           | Failed to write document    |
| `COLLECTION_DELETE_ERROR`          | Failed to delete document   |
| `COLLECTION_REGISTRY_ERROR`        | Schema registry load failed |
| `COLLECTION_VIEW_NOT_FOUND`        | View not found              |
| `COLLECTION_ACTION_NOT_FOUND`      | Action not found            |
| `COLLECTION_CONTEXT_FACTORY_ERROR` | Context factory failed      |

***

## Next Steps

<Cards>
  <Card title="Troubleshooting" description="Common errors and how to fix them." href="/docs/collections/troubleshooting" />

  <Card title="Best Practices" description="Patterns, anti-patterns, and performance tips." href="/docs/collections/best-practices" />

  <Card title="Framework Integration" description="Next.js, Express, Astro, and Remix examples." href="/docs/collections/framework-integration" />
</Cards>


---

# Best Practices

> Do's and Don'ts, proven patterns, anti-patterns to avoid, and performance optimization tips for production collections.
URL: https://igniterjs.com/docs/collections/best-practices

## Best Practices

Guidelines for writing maintainable, performant, and type-safe collections code.

***

## ✅ Do's

### 1. Use Descriptive Collection Names

```typescript
// ✅ Clear, plural, domain-specific
const BlogPosts = IgniterCollectionModel.create('posts')
const ProductPages = IgniterCollectionModel.create('products')
const UserProfiles = IgniterCollectionModel.create('profiles')

// ❌ Vague or abbreviated
const P = IgniterCollectionModel.create('p')
const Data = IgniterCollectionModel.create('data')
```

### 2. Centralize Schema Definitions

```typescript
// ✅ Define schemas separately for reuse
// schemas/post.schema.ts
export const postSchema = z.object({
  title: z.string().min(1),
  published: z.boolean().default(false),
  tags: z.array(z.string()).default([]),
});

// collections/posts.ts
import { postSchema } from '../schemas/post.schema';

const Posts = IgniterCollectionModel.create('posts')
  .withSchema(postSchema)
  .build();

// Also use for type exports
export type Post = z.infer<typeof postSchema>;
```

### 3. Always Paginate

```typescript
// ✅ Paginate every list query
const posts = await docs.posts.findMany({
  take: 20,
  skip: (page - 1) * 20,
  orderBy: { createdAt: 'desc' as const },
});

// ❌ Loading unbounded results
const allPosts = await docs.posts.findMany();
```

### 4. Use Select for Network Efficiency

```typescript
// ✅ Return only what you need
const titles = await docs.posts.findMany({
  select: { id: true, title: true, slug: true },
  take: 50,
});

// ❌ Return everything including content
const posts = await docs.posts.findMany({ take: 50 });
// Each document includes the full content body
```

### 5. Handle Errors Gracefully

```typescript
// ✅ Structured error handling
import { IgniterCollectionError } from '@igniter-js/collections';

try {
  await docs.posts.create({ data: { title: 'Hello' } });
} catch (error) {
  if (error instanceof IgniterCollectionError) {
    switch (error.code) {
      case 'COLLECTION_VALIDATION_ERROR':
        return { error: 'Invalid data', details: error.details };
      case 'COLLECTION_HOOK_CANCELLED':
        return { error: 'Operation rejected by business rules' };
      default:
        return { error: 'Internal error' };
    }
  }
  throw error; // Re-throw unexpected errors
}
```

### 6. Clean Up Event Subscriptions

```typescript
// ✅ Store handles for cleanup
class ContentService {
  private handles: Array<() => void> = [];

  start() {
    this.handles.push(
      docs.on('posts:created', this.onPostCreated).off
    );
    this.handles.push(
      docs.on('posts:deleted', this.onPostDeleted).off
    );
  }

  stop() {
    this.handles.forEach(off => off());
    this.handles = [];
  }
}
```

### 7. Use Context for Dependency Injection

```typescript
// ✅ Inject dependencies through context
const docs = IgniterCollections.create()
  .withAdapter(adapter)
  .withContext(async () => ({
    db: await Database.connect(),
    cache: new Cache(),
  }))
  .addCollection(Posts)
  .build();

Posts.onCreated(async ({ value, context }) => {
  const { cache } = context as { cache: Cache };
  cache.delete('posts:list');
  return value;
});
```

***

## ❌ Don'ts

### 1. Don't Use Hooks for Heavy Async Work

```typescript
// ❌ Hooks block the operation
.onCreated(async ({ value }) => {
  await sendEmail({ to: 'everyone@company.com' }); // Slow!
  return value;
})

// ✅ Delegate to background processing
.onCreated(async ({ value }) => {
  backgroundQueue.add('post-created', { id: value.id });
  return value;
})
```

### 2. Don't Modify Documents Outside the Manager

```typescript
// ❌ Direct file manipulation bypasses hooks, validation, and events
import { writeFile } from 'fs/promises';
await writeFile('.content/posts/my-post.mdx', rawMarkdown);

// ✅ Always use the manager
await docs.posts.update({
  where: { id: 'my-post' },
  data: { title: 'Updated Title' },
});
```

### 3. Don't Create Too Many Sub-Collections

```typescript
// ❌ Deep nesting makes queries complex
Posts.collections.create('comments')
  .collections.create('replies')
    .collections.create('reactions')
      .collections.create('emoji') // Too deep!

// ✅ Keep it to 2-3 levels max
Posts.collections.create('comments')
  .collections.create('replies')
```

### 4. Don't Use Zod `transform` in Schemas

```typescript
// ❌ Transforms break type inference
const schema = z.object({
  date: z.string().transform(s => new Date(s)),
});

// ✅ Transform in hooks instead
.onCreated(({ value }) => {
  value.data.parsedDate = new Date(value.data.dateString);
  return value;
})
```

### 5. Don't Query Without Index Considerations

```typescript
// ❌ Full scan on large collections
await docs.posts.findMany({
  where: { author: 'Felipe' },
});

// ✅ Use pagination + full-text search where possible
await docs.posts.findMany({
  where: {
    author: 'Felipe',
    search: { term: 'TypeScript' }, // Leverages MiniSearch index
  },
  take: 20,
});
```

***

## Performance Tips

### Batch Operations

```typescript
// ✅ Batch creates with Promise.all
const posts = await Promise.all(
  importData.map(item =>
    docs.posts.create({
      data: {
        title: item.title,
        author: item.author,
        published: false,
      }
    })
  )
);
```

### Avoid N+1 with Sub-Collections

```typescript
// ❌ N+1: fetching comments for each post individually
const posts = await docs.posts.findMany({ take: 10 });
for (const post of posts) {
  const comments = await docs.posts.collections.get('comments').findMany({
    where: { parentId: post.id },
  });
}

// ✅ Use include
const posts = await docs.posts.findMany({
  take: 10,
  include: { comments: true },
});
```

### Caching Strategy

```typescript
let cachedPosts: Post[] | null = null;
let cacheTimestamp = 0;
const CACHE_TTL = 60_000; // 1 minute

async function getPosts() {
  if (cachedPosts && Date.now() - cacheTimestamp < CACHE_TTL) {
    return cachedPosts;
  }

  cachedPosts = await docs.posts.findMany({
    where: { published: true },
    orderBy: { createdAt: 'desc' as const },
    take: 20,
  });
  cacheTimestamp = Date.now();
  return cachedPosts;
}

// Invalidate on changes
docs.on('posts:created', () => { cachedPosts = null; });
docs.on('posts:updated', () => { cachedPosts = null; });
```

***

## Project Structure

Recommended file organization for a collections-powered project:

```
src/
├── collections/
│   ├── posts.ts         # Post collection definition
│   ├── pages.ts         # Page collection definition
│   └── authors.ts       # Author collection definition
├── schemas/
│   ├── post.schema.ts   # Zod schemas (reusable)
│   ├── page.schema.ts
│   └── author.schema.ts
├── views/
│   ├── dashboard.ts     # Dashboard view definition
│   └── content-audit.ts # Audit view definition
├── hooks/
│   ├── slugify.ts       # Hook: auto-generate slugs
│   └── audit-log.ts     # Hook: audit trail
├── adapters/
│   └── storage.ts       # Adapter factory (env-based)
└── manager.ts           # Central manager bootstrap
```

***

## Next Steps

<Cards>
  <Card title="Framework Integration" description="Next.js, Express, Astro, and Remix examples." href="/docs/collections/framework-integration" />

  <Card title="Troubleshooting" description="Common errors and how to fix them." href="/docs/collections/troubleshooting" />

  <Card title="API Reference" description="Complete reference for all builders and managers." href="/docs/collections/api-reference" />
</Cards>


---

# CRUD Operations

> Complete guide to create, findUnique, findMany, update, delete, and count operations with full TypeScript type safety.
URL: https://igniterjs.com/docs/collections/crud-operations

## CRUD Operations

Every collection provides six core operations. All are fully typed — your Zod schema drives the TypeScript inference for every parameter and return type.

<Callout type="info">
  All examples assume a `Posts` collection is registered on `docs`. See [Defining Collections](/docs/collections/defining-collections) for setup.
</Callout>

***

## `create()`

Creates a new document with validated frontmatter and optional Markdown content.

### Signature

```typescript
create(args: {
  data: PostData & { content?: string };
  id?: string;
  select?: SelectObject<PostData>;
  exclude?: ExcludeObject<PostData>;
}): Promise<IgniterCollectionDocument<PostData>>
```

### Basic Usage

```typescript
const post = await docs.posts.create({
  data: {
    title: 'Getting Started with Igniter.js',
    description: 'Learn the basics',
    published: true,
    tags: ['tutorial', 'typescript'],
    author: 'Felipe Barcelos',
  }
});

console.log(post.id);        // 'a1b2c3d4-...' (auto-generated UUID)
console.log(post.title);     // 'Getting Started with Igniter.js'
console.log(post.createdAt); // ISO timestamp
```

### With Content

```typescript
const post = await docs.posts.create({
  data: {
    title: 'My First Post',
    published: true,
    author: 'Felipe',
    content: `## Introduction

This is the full Markdown body of the document.`,
  }
});
```

### With Custom ID

```typescript
const post = await docs.posts.create({
  id: 'getting-started', // Custom slug
  data: {
    title: 'Getting Started',
    published: true,
    author: 'Felipe',
  }
});
```

### Return Value

The returned `IgniterCollectionDocument` includes:

| Field             | Type                  | Description                          |
| ----------------- | --------------------- | ------------------------------------ |
| `id`              | `string`              | Document ID                          |
| `path`            | `string`              | Absolute file path                   |
| `content`         | `string`              | Markdown body                        |
| `createdAt`       | `string`              | ISO creation timestamp               |
| `updatedAt`       | `string`              | ISO update timestamp                 |
| `parentId`        | `string \| undefined` | Parent document ID (sub-collections) |
| `...schemaFields` | Inferred from Zod     | All frontmatter fields               |

***

## `findUnique()`

Finds a single document by its ID. Returns `null` if not found.

### Signature

```typescript
findUnique(args: {
  where: { id: string };
  select?: SelectObject<PostData>;
  exclude?: ExcludeObject<PostData>;
}): Promise<IgniterCollectionDocument<PostData> | null>
```

### Basic Usage

```typescript
const post = await docs.posts.findUnique({
  where: { id: 'a1b2c3d4-...' }
});

if (post) {
  console.log(post.title); // 'Getting Started'
} else {
  console.log('Post not found');
}
```

### With Field Selection

```typescript
const post = await docs.posts.findUnique({
  where: { id: 'a1b2c3d4-...' },
  select: { title: true, author: true, published: true },
});
// Only title, author, and published are returned
```

***

## `findMany()`

Queries documents with filters, sorting, pagination, and full-text search.

### Signature

```typescript
findMany(args?: {
  where?: WhereClause<PostData>;
  orderBy?: OrderByClause<PostData>;
  take?: number;
  skip?: number;
  select?: SelectObject<PostData>;
  exclude?: ExcludeObject<PostData>;
  include?: IncludeClause;
}): Promise<IgniterCollectionDocument<PostData>[]>
```

### Basic Usage

```typescript
// Get all posts
const allPosts = await docs.posts.findMany();

// Get published posts, newest first
const published = await docs.posts.findMany({
  where: { published: true },
  orderBy: { createdAt: 'desc' as const },
});

// Paginate
const page = await docs.posts.findMany({
  take: 10,
  skip: 20,  // page 3
  orderBy: { createdAt: 'desc' as const },
});
```

### Filtering

```typescript
// Exact match
await docs.posts.findMany({ where: { author: 'Felipe' } });

// Multiple conditions
await docs.posts.findMany({
  where: {
    published: true,
    author: 'Felipe',
  }
});

// Filter operators
await docs.posts.findMany({
  where: {
    views: { gte: 100 },
    tags: { has: 'featured' },
  }
});
```

See [Querying](/docs/collections/querying) for the complete filtering reference.

***

## `update()`

Updates an existing document. Only the fields you provide are changed.

### Signature

```typescript
update(args: {
  where: { id: string };
  data: Partial<PostData & { content?: string }>;
  select?: SelectObject<PostData>;
  exclude?: ExcludeObject<PostData>;
}): Promise<IgniterCollectionDocument<PostData>>
```

### Basic Usage

```typescript
const updated = await docs.posts.update({
  where: { id: 'a1b2c3d4-...' },
  data: {
    title: 'Updated Title',
    published: true,
  }
});

// Only title and published change; all other fields remain
console.log(updated.title);     // 'Updated Title'
console.log(updated.published); // true
```

### Updating Content

```typescript
const updated = await docs.posts.update({
  where: { id: 'a1b2c3d4-...' },
  data: {
    content: '## Updated Content\n\nThe body has been revised.',
  }
});
```

<Callout type="warn">
  **Partial updates only.** You don't need to pass all fields — collections merges the provided data with the existing document.
</Callout>

***

## `delete()`

Permanently deletes a document.

### Signature

```typescript
delete(args: {
  where: { id: string };
  select?: SelectObject<PostData>;
  exclude?: ExcludeObject<PostData>;
}): Promise<IgniterCollectionDocument<PostData>>
```

### Usage

```typescript
const deleted = await docs.posts.delete({
  where: { id: 'a1b2c3d4-...' }
});

console.log(deleted.id); // The deleted document is returned
```

<Callout type="warn">
  **Deletion is permanent.** The file is removed from the adapter. Use an `onDeleted` hook if you need soft-delete or archival behavior.
</Callout>

***

## `count()`

Counts documents matching optional filters.

### Signature

```typescript
count(args?: {
  where?: WhereClause<PostData>;
}): Promise<number>
```

### Usage

```typescript
// Count all posts
const total = await docs.posts.count();

// Count published posts
const publishedCount = await docs.posts.count({
  where: { published: true }
});

// Count with operators
const popularCount = await docs.posts.count({
  where: { views: { gte: 1000 } }
});
```

***

## Select & Exclude

Both `select` and `exclude` control which fields are returned. They are **mutually exclusive** — use one or the other, not both.

### Select (whitelist)

```typescript
const posts = await docs.posts.findMany({
  select: { id: true, title: true, author: true },
});
// Only id, title, and author returned
```

### Exclude (blacklist)

```typescript
const posts = await docs.posts.findMany({
  exclude: { content: true },
});
// Everything except content returned
```

### Deep Select

```typescript
const posts = await docs.posts.findMany({
  select: {
    id: true,
    title: true,
    metadata: {
      seoTitle: true,
      // seoDescription excluded from metadata
    },
  },
});
```

***

## Error Handling

All CRUD operations throw `IgniterCollectionError` with structured error codes:

```typescript
import { IgniterCollectionError, IGNITER_COLLECTION_ERROR_CODES } from '@igniter-js/collections';

try {
  await docs.posts.create({ data: { title: '' } }); // Fails validation
} catch (error) {
  if (error instanceof IgniterCollectionError) {
    console.log(error.code);    // 'COLLECTION_VALIDATION_ERROR'
    console.log(error.message); // 'Validation failed: Title is required'
    console.log(error.details); // { issues: [...] }
  }
}
```

See [Troubleshooting](/docs/collections/troubleshooting) for all error codes and solutions.

***

## Real-World Example: Blog Engine

A complete blog engine with drafts, publishing workflow, and pagination:

```typescript
// Define the collection
const Posts = IgniterCollectionModel.create('posts')
  .withPatterns(['.content/posts/{year}/{month}/{id}.mdx'])
  .withSchema(z.object({
    title: z.string().min(1),
    slug: z.string(),
    excerpt: z.string().max(300),
    published: z.boolean().default(false),
    featured: z.boolean().default(false),
    tags: z.array(z.string()).default([]),
    author: z.string(),
    coverImage: z.string().url().optional(),
  }))
  .build();

const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .addCollection(Posts)
  .build();

// --- Operations ---

// 1. Create a draft
const draft = await docs.posts.create({
  id: 'my-awesome-post',
  data: {
    title: 'My Awesome Post',
    slug: 'my-awesome-post',
    excerpt: 'A deep dive into modern TypeScript patterns.',
    published: false,
    featured: true,
    tags: ['typescript', 'patterns'],
    author: 'Felipe Barcelos',
  }
});

// 2. Publish it
const published = await docs.posts.update({
  where: { id: draft.id },
  data: { published: true },
});

// 3. Query the blog homepage
const featured = await docs.posts.findMany({
  where: { published: true, featured: true },
  orderBy: { createdAt: 'desc' as const },
  take: 5,
});

// 4. Tag archive page
const typescriptPosts = await docs.posts.findMany({
  where: {
    published: true,
    tags: { has: 'typescript' },
  },
  orderBy: { createdAt: 'desc' as const },
  take: 20,
});

// 5. Stats
const stats = {
  total: await docs.posts.count(),
  published: await docs.posts.count({ where: { published: true } }),
  drafts: await docs.posts.count({ where: { published: false } }),
};
```

***

## Next Steps

<Cards>
  <Card title="Querying" description="Deep dive into filtering, sorting, pagination, and full-text search." href="/docs/collections/querying" />

  <Card title="Hooks" description="Add lifecycle hooks for validation, enrichment, and cancellation." href="/docs/collections/hooks" />

  <Card title="Events" description="Subscribe to document lifecycle events." href="/docs/collections/events" />
</Cards>


---

# Defining Collections

> Define type-safe content collections with Zod schemas, file patterns, sub-collections, templates, and custom ID generators.
URL: https://igniterjs.com/docs/collections/defining-collections

## Defining Collections

A **collection** is the core building block of `@igniter-js/collections`. It defines:

* A **name** for access (`docs.posts`)
* A **schema** for frontmatter validation
* **File patterns** for where documents are stored
* Optional **hooks** for lifecycle control
* Optional **sub-collections** for nested documents

***

## Basic Collection

The simplest collection requires a name, a file pattern, and a schema:

```typescript
import { IgniterCollectionModel } from '@igniter-js/collections';
import { z } from 'zod';

const Posts = IgniterCollectionModel.create('posts')
  .withPatterns(['.content/posts/{id}.mdx'])
  .withSchema(z.object({
    title: z.string(),
    description: z.string(),
    published: z.boolean().default(false),
    tags: z.array(z.string()).optional(),
    author: z.string(),
  }))
  .build();
```

<Callout type="info">
  The collection name (`'posts'`) determines the accessor on the manager: `docs.posts.create(...)`.
  Use descriptive, plural names that match your domain.
</Callout>

***

## File Patterns

File patterns define where and how documents are stored on disk. The pattern uses placeholder variables inside `{braces}`.

### Built-in Placeholders

| Placeholder                  | Description                          | Example                                 |
| ---------------------------- | ------------------------------------ | --------------------------------------- |
| `{id}`                       | Document UUID                        | `posts/{id}.mdx` → `posts/a1b2c3d4.mdx` |
| `{parent_id}`                | Parent document ID (sub-collections) | `{parent_id}/comments/{id}.mdx`         |
| `{year}`, `{month}`, `{day}` | Date-based (from `createdAt`)        | `posts/{year}/{month}/{id}.mdx`         |
| Custom fields                | Any schema field                     | `posts/{author}/{id}.mdx`               |

### Pattern Examples

```typescript
// Flat structure
.withPatterns(['.content/posts/{id}.mdx'])

// Date-based organization (auto-resolved from createdAt)
.withPatterns(['.content/posts/{year}/{month}/{id}.mdx'])

// Author-based organization
.withPatterns(['.content/posts/{author}/{id}.mdx'])

// Multiple patterns — the best match is used
.withPatterns([
  '.content/posts/{year}/{month}/{id}.mdx',
  '.content/posts/{id}.mdx',
])
```

<Callout type="warn">
  **Pattern variables must exist in the schema or be a built-in placeholder.** If a variable like `{author}` is used, the schema must include an `author` field. Built-in placeholders (`id`, `parent_id`, date fields) are always available.
</Callout>

***

## Schema Validation

Collections uses Zod (via the StandardSchemaV1 interface) for frontmatter validation. Every `create` and `update` call runs through the validator before writing to disk.

```typescript
const Posts = IgniterCollectionModel.create('posts')
  .withSchema(z.object({
    title: z.string().min(1, 'Title is required'),
    slug: z.string().regex(/^[a-z0-9-]+$/, 'Slug must be URL-safe'),
    published: z.boolean().default(false),
    views: z.number().int().min(0).default(0),
    tags: z.array(z.string()).max(10).default([]),
    metadata: z.object({
      seoTitle: z.string().optional(),
      seoDescription: z.string().max(160).optional(),
    }).optional(),
  }))
  .build();
```

When validation fails, an `IgniterCollectionError` is thrown with code `COLLECTION_VALIDATION_ERROR` and detailed issue information.

### Type Inference

The TypeScript type is **automatically inferred** from your Zod schema:

```typescript
// Posts.data is typed as:
type PostData = {
  title: string;
  slug: string;
  published: boolean;
  views: number;
  tags: string[];
  metadata?: {
    seoTitle?: string;
    seoDescription?: string;
  };
};

// create() gets full IntelliSense:
const post = await docs.posts.create({
  data: {
    title: 'Hello',      // ✅ string
    slug: 'hello-world', // ✅ string
    // published: 'yes', // ❌ Type error — expected boolean
  }
});
```

***

## Document Content

Every document has two parts: **frontmatter** (validated by the schema) and **content** (the Markdown body). Content is passed alongside frontmatter data:

```typescript
const post = await docs.posts.create({
  data: {
    title: 'My First Post',
    description: 'An introduction to collections',
    published: true,
    author: 'Felipe',
    content: `## Introduction

This is the **Markdown body** of the document.

It supports full Markdown syntax including code blocks, images, and tables.`,
  }
});

// Access content separately from frontmatter
console.log(post.title);       // 'My First Post'
console.log(post.content);     // '## Introduction\n\nThis is the **Markdown body**...'
```

***

## Sub-Collections

Sub-collections allow nested document hierarchies — perfect for comments on posts, tasks in a project, or variants of a product.

```typescript
const Posts = IgniterCollectionModel.create('posts')
  .withPatterns(['.content/posts/{id}.mdx'])
  .withSchema(postSchema)
  .build();

// Define a sub-collection using the parent
const Comments = Posts.collections.create('comments')
  .withPatterns(['{parent_id}/comments/{id}.mdx'])
  .withSchema(z.object({
    author: z.string(),
    body: z.string(),
    approved: z.boolean().default(false),
  }))
  .build();
```

Sub-collections are accessed through the parent document and stored relative to it. The `{parent_id}` placeholder resolves to the parent document's ID.

***

## Custom ID Generators

By default, collections generates **UUID v4** IDs. You can provide a custom generator for human-friendly slugs or sequential IDs:

```typescript
const Posts = IgniterCollectionModel.create('posts')
  .withPatterns(['.content/posts/{id}.mdx'])
  .withSchema(postSchema)
  .build();

// Override the ID when creating
const post = await docs.posts.create({
  id: 'getting-started-with-igniter', // Custom slug
  data: {
    title: 'Getting Started',
    author: 'Felipe',
  }
});
```

<Callout type="info">
  The `id` parameter on `create()` accepts any string. If omitted, the default UUID v4 generator runs automatically.
</Callout>

***

## Next Steps

<Cards>
  <Card title="CRUD Operations" description="Learn create, findUnique, findMany, update, delete, and count." href="/docs/collections/crud-operations" />

  <Card title="Querying" description="Filter, sort, paginate, and search your collections." href="/docs/collections/querying" />

  <Card title="Hooks" description="Add lifecycle hooks for validation, enrichment, and cancellation." href="/docs/collections/hooks" />
</Cards>


---

# Events

> Subscribe to document lifecycle events globally or per-collection. Build reactive systems with typed event handlers and subscription management.
URL: https://igniterjs.com/docs/collections/events

## Events

Collections emits typed events for every document operation. Subscribe globally (across all collections) or scoped to a single collection. Every subscription returns a handle with an `off()` method for cleanup.

***

## Event Types

### Global Events

Global events fire for **any collection**. The payload includes the collection name:

| Event     | Payload                                            | When                 |
| --------- | -------------------------------------------------- | -------------------- |
| `created` | `{ collection, value, context }`                   | Any document created |
| `updated` | `{ collection, newValue, previousValue, context }` | Any document updated |
| `deleted` | `{ collection, value, context }`                   | Any document deleted |
| `read`    | `{ collection, value, context }`                   | Any document read    |

### Scoped Events

Scoped events fire for a **specific collection**. Use the format `{collectionName}:{event}`:

| Event Pattern   | Payload                                |
| --------------- | -------------------------------------- |
| `posts:created` | `{ value, context }`                   |
| `posts:updated` | `{ newValue, previousValue, context }` |
| `posts:deleted` | `{ value, context }`                   |
| `posts:read`    | `{ value, context }`                   |

***

## Subscribing to Events

### Global Subscriptions

```typescript
import { IgniterCollections } from '@igniter-js/collections';

// Subscribe with cleanup handle
const { off } = docs.on('created', ({ collection, value }) => {
  console.log(`Document created in ${collection}: ${value.id}`);
});

// Later: unsubscribe
off();
```

### Scoped Subscriptions

```typescript
// Listen to a specific collection
docs.on('posts:updated', ({ newValue, previousValue }) => {
  console.log(`Post updated: ${newValue.id}`);
  console.log('Previous title:', previousValue.title);
  console.log('New title:', newValue.title);
});
```

### Model-Level Subscriptions

You can also subscribe directly on a collection manager:

```typescript
// Access the collection manager
const postsManager = docs.collections.get('posts');

// Subscribe to collection-specific events (no name prefix needed)
const { off } = postsManager.on('created', ({ value }) => {
  console.log(`Post created: ${value.title}`);
});

off(); // Cleanup
```

***

## Subscription Handle

Every `on()` call returns an `IgniterCollectionSubscription`:

```typescript
interface IgniterCollectionSubscription {
  off(): void; // Unsubscribe the handler
}
```

```typescript
// Store handles for cleanup
const handles = [];

handles.push(
  docs.on('created', ({ collection, value }) => {
    log.info(`[${collection}] Created: ${value.id}`);
  }).off
);

handles.push(
  docs.on('posts:updated', ({ newValue }) => {
    cache.invalidate(`post:${newValue.id}`);
  }).off
);

// Cleanup all at once
function cleanup() {
  handles.forEach(off => off());
}
```

***

## Real-World Patterns

### Activity Feed

```typescript
const activities: Activity[] = [];

docs.on('created', ({ collection, value }) => {
  activities.push({
    type: 'created',
    collection,
    documentId: value.id,
    title: value.title,
    timestamp: new Date().toISOString(),
  });
});

docs.on('updated', ({ collection, newValue }) => {
  activities.push({
    type: 'updated',
    collection,
    documentId: newValue.id,
    title: newValue.title,
    timestamp: new Date().toISOString(),
  });
});

docs.on('deleted', ({ collection, value }) => {
  activities.push({
    type: 'deleted',
    collection,
    documentId: value.id,
    title: value.title,
    timestamp: new Date().toISOString(),
  });
});
```

### Cache Invalidation

```typescript
docs.on('posts:updated', ({ newValue }) => {
  cache.delete(`post:${newValue.id}`);
  cache.delete(`post:${newValue.slug}`);
  cache.delete('posts:list');
});

docs.on('posts:deleted', ({ value }) => {
  cache.delete(`post:${value.id}`);
  cache.delete(`post:${value.slug}`);
  cache.delete('posts:list');
});
```

### Rebuild Search Index

```typescript
docs.on('posts:created', async ({ value }) => {
  await searchIndex.add(value);
});

docs.on('posts:updated', async ({ newValue }) => {
  await searchIndex.update(newValue);
});

docs.on('posts:deleted', async ({ value }) => {
  await searchIndex.remove(value.id);
});
```

### Webhook Notifications

```typescript
docs.on('posts:created', async ({ value }) => {
  if (value.published) {
    await fetch('https://api.example.com/webhooks/content', {
      method: 'POST',
      body: JSON.stringify({
        event: 'post.published',
        post: { id: value.id, title: value.title, slug: value.slug },
      }),
    });
  }
});
```

***

## Error Handling in Handlers

Handlers execute concurrently and errors in one handler do not stop others:

```typescript
docs.on('created', async ({ value }) => {
  // This will log an error but won't affect other handlers
  throw new Error('Something went wrong');
});

docs.on('created', ({ value }) => {
  // This handler still runs
  console.log('Second handler still executed');
});
```

<Callout type="info">
  Event handlers run **after** the operation completes successfully. If a hook cancels the operation (`return false`), no event is emitted.
</Callout>

***

## Next Steps

<Cards>
  <Card title="Views" description="Define data-driven views with component trees and actions." href="/docs/collections/views" />

  <Card title="Hooks" description="Control operations with lifecycle hooks." href="/docs/collections/hooks" />

  <Card title="Advanced" description="Context injection, telemetry, and advanced patterns." href="/docs/collections/advanced" />
</Cards>


---

# Framework Integration

> Integrate collections with Next.js, Express, Astro, and Remix. Complete examples with routing, caching, and deployment patterns.
URL: https://igniterjs.com/docs/collections/framework-integration

## Framework Integration

Collections is framework-agnostic — it works with any JavaScript runtime. Here are integration patterns for popular frameworks.

***

## Next.js

Collections integrates naturally with Next.js App Router, Server Components, and Route Handlers.

### Singleton Manager

Create a singleton manager for reuse across requests:

```typescript title="lib/collections.ts"
import { IgniterCollections, IgniterCollectionModel } from '@igniter-js/collections';
import { NodeFsAdapter } from '@igniter-js/collections/adapters';
import { z } from 'zod';

const Posts = IgniterCollectionModel.create('posts')
  .withPatterns(['content/posts/{id}.mdx'])
  .withSchema(z.object({
    title: z.string(),
    slug: z.string(),
    excerpt: z.string().max(300),
    published: z.boolean().default(false),
    tags: z.array(z.string()).default([]),
    author: z.string(),
  }))
  .build();

// Singleton — initialized once at module level
export const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .addCollection(Posts)
  .build();
```

### Server Component (App Router)

```typescript title="app/blog/page.tsx"
import { docs } from '@/lib/collections';

export default async function BlogPage() {
  const posts = await docs.posts.findMany({
    where: { published: true },
    orderBy: { createdAt: 'desc' as const },
    take: 20,
    select: { id: true, title: true, slug: true, excerpt: true, tags: true },
  });

  return (
    <main>
      <h1>Blog</h1>
      {posts.map(post => (
        <article key={post.id}>
          <h2><a href={`/blog/${post.slug}`}>{post.title}</a></h2>
          <p>{post.excerpt}</p>
          <div>{post.tags.map(t => <span key={t}>{t}</span>)}</div>
        </article>
      ))}
    </main>
  );
}
```

### Dynamic Route (generateStaticParams)

```typescript title="app/blog/[slug]/page.tsx"
import { docs } from '@/lib/collections';
import { notFound } from 'next/navigation';

export async function generateStaticParams() {
  const posts = await docs.posts.findMany({
    where: { published: true },
    select: { slug: true },
  });

  return posts.map(post => ({ slug: post.slug }));
}

export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;

  const post = await docs.posts.findUnique({
    where: { slug },
  });

  if (!post) notFound();

  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}
```

### API Route Handler

```typescript title="app/api/posts/route.ts"
import { docs } from '@/lib/collections';
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const page = parseInt(searchParams.get('page') || '1');
  const tag = searchParams.get('tag');

  const where: any = { published: true };
  if (tag) where.tags = { has: tag };

  const [posts, total] = await Promise.all([
    docs.posts.findMany({
      where,
      orderBy: { createdAt: 'desc' as const },
      take: 20,
      skip: (page - 1) * 20,
    }),
    docs.posts.count({ where }),
  ]);

  return NextResponse.json({
    posts,
    total,
    page,
    totalPages: Math.ceil(total / 20),
  });
}
```

***

## Express

Collections as middleware in an Express application.

```typescript title="src/server.ts"
import express from 'express';
import { IgniterCollections, IgniterCollectionModel } from '@igniter-js/collections';
import { NodeFsAdapter } from '@igniter-js/collections/adapters';
import { z } from 'zod';

const Posts = IgniterCollectionModel.create('posts')
  .withPatterns(['content/posts/{id}.mdx'])
  .withSchema(z.object({
    title: z.string(),
    published: z.boolean().default(false),
    author: z.string(),
  }))
  .build();

const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .addCollection(Posts)
  .build();

const app = express();
app.use(express.json());

// List posts
app.get('/api/posts', async (req, res) => {
  const page = parseInt(req.query.page as string) || 1;
  const posts = await docs.posts.findMany({
    where: { published: true },
    orderBy: { createdAt: 'desc' as const },
    take: 20,
    skip: (page - 1) * 20,
    select: { id: true, title: true, author: true, createdAt: true },
  });
  res.json({ posts });
});

// Get single post
app.get('/api/posts/:id', async (req, res) => {
  const post = await docs.posts.findUnique({
    where: { id: req.params.id },
  });
  if (!post) return res.status(404).json({ error: 'Not found' });
  res.json(post);
});

// Create post
app.post('/api/posts', async (req, res) => {
  try {
    const post = await docs.posts.create({
      data: {
        title: req.body.title,
        author: req.body.author,
        published: req.body.published ?? false,
        content: req.body.content,
      },
    });
    res.status(201).json(post);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

app.listen(3000, () => console.log('Server running on :3000'));
```

***

## Astro

Collections in Astro with content collections and SSR.

```typescript title="src/lib/collections.ts"
import { IgniterCollections, IgniterCollectionModel } from '@igniter-js/collections';
import { NodeFsAdapter } from '@igniter-js/collections/adapters';
import { z } from 'zod';

const Posts = IgniterCollectionModel.create('posts')
  .withPatterns(['src/content/posts/{id}.mdx'])
  .withSchema(z.object({
    title: z.string(),
    description: z.string(),
    published: z.boolean().default(false),
    tags: z.array(z.string()).default([]),
  }))
  .build();

export const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .addCollection(Posts)
  .build();
```

```astro title="src/pages/blog/index.astro"
---
import { docs } from '../../lib/collections';

const posts = await docs.posts.findMany({
  where: { published: true },
  orderBy: { createdAt: 'desc' as const },
  take: 20,
});
---

<Layout>
  <h1>Blog</h1>
  {posts.map(post => (
    <article>
      <h2><a href={`/blog/${post.id}`}>{post.title}</a></h2>
      <p>{post.description}</p>
    </article>
  ))}
</Layout>
```

```astro title="src/pages/blog/[id].astro"
---
import { docs } from '../../lib/collections';

export async function getStaticPaths() {
  const posts = await docs.posts.findMany({
    select: { id: true },
  });
  return posts.map(post => ({ params: { id: post.id } }));
}

const { id } = Astro.params;
const post = await docs.posts.findUnique({ where: { id } });
---

<Layout>
  <h1>{post.title}</h1>
  <article set:html={post.content} />
</Layout>
```

***

## Remix

Collections as a loader data source in Remix.

```typescript title="app/lib/collections.server.ts"
import { IgniterCollections, IgniterCollectionModel } from '@igniter-js/collections';
import { NodeFsAdapter } from '@igniter-js/collections/adapters';
import { z } from 'zod';

const Posts = IgniterCollectionModel.create('posts')
  .withPatterns(['content/posts/{id}.mdx'])
  .withSchema(z.object({
    title: z.string(),
    slug: z.string(),
    published: z.boolean().default(false),
    author: z.string(),
  }))
  .build();

// Server-only singleton
export const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .addCollection(Posts)
  .build();
```

```typescript title="app/routes/blog._index.tsx"
import { json, useLoaderData } from '@remix-run/react';
import { docs } from '~/lib/collections.server';

export async function loader() {
  const posts = await docs.posts.findMany({
    where: { published: true },
    orderBy: { createdAt: 'desc' as const },
    take: 20,
  });
  return json({ posts });
}

export default function BlogIndex() {
  const { posts } = useLoaderData<typeof loader>();

  return (
    <main>
      <h1>Blog</h1>
      {posts.map(post => (
        <article key={post.id}>
          <h2><a href={`/blog/${post.slug}`}>{post.title}</a></h2>
        </article>
      ))}
    </main>
  );
}
```

```typescript title="app/routes/blog.$slug.tsx"
import { json, useLoaderData } from '@remix-run/react';
import { docs } from '~/lib/collections.server';
import { notFound } from 'remix-utils';

export async function loader({ params }: LoaderFunctionArgs) {
  const post = await docs.posts.findUnique({
    where: { slug: params.slug! },
  });

  if (!post || !post.published) throw notFound({ slug: params.slug });

  return json({ post });
}

export default function BlogPost() {
  const { post } = useLoaderData<typeof loader>();

  return (
    <article>
      <h1>{post.title}</h1>
      <p>By {post.author}</p>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}
```

***

## Deployment Patterns

### Vercel / Netlify (Serverless)

```typescript title="lib/collections.ts"
// Use a lazy singleton for cold starts
let _docs: ReturnType<typeof createDocs> | null = null;

function createDocs() {
  return IgniterCollections.create()
    .withAdapter(new NodeFsAdapter())
    .withBasePath(process.cwd())
    .addCollection(Posts)
    .build();
}

export function getDocs() {
  if (!_docs) _docs = createDocs();
  return _docs;
}
```

### Docker / Long-Running Server

```typescript title="lib/collections.ts"
// Eager initialization for persistent servers
export const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .addCollection(Posts)
  .build();
```

### Edge Runtime (S3 Adapter)

```typescript title="lib/collections.ts"
import { BunS3Adapter } from '@igniter-js/collections/adapters';

export const docs = IgniterCollections.create()
  .withAdapter(new BunS3Adapter({
    bucket: process.env.CONTENT_BUCKET!,
    region: process.env.AWS_REGION!,
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    },
  }))
  .addCollection(Posts)
  .build();
```

***

## Next Steps

<Cards>
  <Card title="Best Practices" description="Patterns, anti-patterns, and performance tips." href="/docs/collections/best-practices" />

  <Card title="Troubleshooting" description="Common errors and how to fix them." href="/docs/collections/troubleshooting" />

  <Card title="API Reference" description="Complete reference for all builders and managers." href="/docs/collections/api-reference" />
</Cards>


---

# Lifecycle Hooks

> Intercept and control document operations with lifecycle hooks. Modify data, enrich documents, and cancel operations by returning false.
URL: https://igniterjs.com/docs/collections/hooks

## Lifecycle Hooks

Hooks let you intercept document operations to **validate**, **enrich**, **transform**, or **cancel** them. Each hook receives a typed context object with the document, collection, and manager references.

There are five hooks, one for each lifecycle event:

| Hook        | When It Runs                          | Can Cancel? | Can Modify? |
| ----------- | ------------------------------------- | ----------- | ----------- |
| `onCreated` | Before a document is written to disk  | ✅           | ✅           |
| `onUpdated` | Before an updated document is written | ✅           | ✅           |
| `onDeleted` | Before a document is deleted          | ✅           | ❌           |
| `onRead`    | After a document is read from disk    | ✅           | ✅           |
| `onList`    | After documents are listed            | ✅           | ✅           |

***

## Hook Context

Every hook receives a context object with these fields:

```typescript
interface HookContext<TSchema> {
  /** The collection manager (for CRUD on this collection) */
  collection: IIgniterCollectionModel<TSchema>;
  /** The main manager (for access to other collections) */
  manager: IIgniterCollectionsManager;
  /** User-defined context from withContext() */
  context: unknown;
}
```

Additional fields depend on the hook type:

| Hook        | Extra Fields                         |
| ----------- | ------------------------------------ |
| `onCreated` | `value` — the document being created |
| `onUpdated` | `newValue`, `previousValue`          |
| `onDeleted` | `value` — the document being deleted |
| `onRead`    | `value` — the document that was read |
| `onList`    | `values` — array of documents        |

***

## `onCreated`

Runs **before** a document is written to disk. You can modify the document or cancel creation.

### Enrich the Document

```typescript
const Posts = IgniterCollectionModel.create('posts')
  .withSchema(postSchema)
  .onCreated(async ({ value }) => {
    // Auto-generate a slug from the title
    value.data.slug = value.title
      .toLowerCase()
      .replace(/[^a-z0-9]+/g, '-')
      .replace(/^-|-$/g, '');

    return value; // Continue with modified document
  })
  .build();
```

### Cancel Creation

```typescript
const Posts = IgniterCollectionModel.create('posts')
  .withSchema(postSchema)
  .onCreated(async ({ value, manager }) => {
    // Prevent duplicate slugs
    const existing = await manager.posts.findMany({
      where: { slug: value.data.slug },
    });

    if (existing.length > 0) {
      return false; // Cancel creation
    }

    return value;
  })
  .build();
```

<Callout type="warn">
  Returning `false` throws an `IgniterCollectionError` with code `COLLECTION_HOOK_CANCELLED`. Make sure to handle this in your calling code.
</Callout>

### Side Effects (Notifications, Indexing)

```typescript
.onCreated(async ({ value }) => {
  await sendNotification({
    channel: '#blog-updates',
    message: `New post: ${value.title} by ${value.author}`,
  });

  return value; // Don't forget to return!
})
```

***

## `onUpdated`

Runs **before** an updated document is written. You have access to both `newValue` and `previousValue`.

### Track Publishing Timestamps

```typescript
const Posts = IgniterCollectionModel.create('posts')
  .withSchema(postSchema)
  .onUpdated(({ newValue, previousValue }) => {
    // Set publishedAt when first published
    if (newValue.data.published && !previousValue.data.published) {
      newValue.data.publishedAt = new Date().toISOString();
    }

    return newValue;
  })
  .build();
```

### Prevent Unpublishing

```typescript
.onUpdated(({ newValue, previousValue }) => {
  if (!newValue.data.published && previousValue.data.published) {
    // Don't allow unpublishing a post that already went live
    return false;
  }

  return newValue;
})
```

### Audit Trail

```typescript
.onUpdated(async ({ newValue, previousValue }) => {
  // Log changes to an audit collection
  await manager.audit.create({
    data: {
      collection: 'posts',
      documentId: newValue.id,
      changedFields: Object.keys(newValue.data).filter(
        k => newValue.data[k] !== previousValue.data[k]
      ),
      timestamp: new Date().toISOString(),
    }
  });

  return newValue;
})
```

***

## `onDeleted`

Runs **before** a document is deleted. Return `true` to proceed or `false` to cancel.

### Soft Delete

```typescript
.onDeleted(async ({ value, manager }) => {
  // Move to archive instead of deleting
  await manager.archive.create({
    data: {
      originalCollection: 'posts',
      originalId: value.id,
      data: value,
      archivedAt: new Date().toISOString(),
    }
  });

  return true; // Allow deletion (archive already created)
})
```

### Prevent Deletion of Published Content

```typescript
.onDeleted(({ value }) => {
  if (value.data.published) {
    return false; // Cannot delete published posts
  }

  return true;
})
```

***

## `onRead`

Runs **after** a document is read. Modify the returned value or suppress it.

### Enrich with Computed Data

```typescript
.onRead(({ value }) => {
  // Add computed reading time
  const wordCount = (value.content || '').split(/\s+/).length;
  value.data.readingTime = Math.ceil(wordCount / 200); // minutes

  return value;
})
```

### Access Control

```typescript
.onRead(({ value, context }) => {
  const { user } = context as { user: User };

  // Hide draft posts from non-admins
  if (!value.data.published && !user.isAdmin) {
    return false; // Suppress — returns null to the caller
  }

  return value;
})
```

***

## `onList`

Runs **after** documents are listed. Filter, sort, or enrich the array.

### Filter Sensitive Content

```typescript
.onList(({ values, context }) => {
  const { user } = context as { user: User };

  if (!user.isAdmin) {
    // Non-admins only see published posts
    return values.filter(v => v.data.published);
  }

  return values;
})
```

### Enrich All Documents

```typescript
.onList(async ({ values, manager }) => {
  // Batch-enrich with author profiles
  const authorNames = [...new Set(values.map(v => v.data.author))];
  const authors = await manager.authors.findMany({
    where: { name: { in: authorNames } },
  });

  const authorMap = new Map(authors.map(a => [a.data.name, a]));

  return values.map(v => ({
    ...v,
    data: { ...v.data, authorProfile: authorMap.get(v.data.author) },
  }));
})
```

***

## Global Hooks

Apply hooks to **all collections** at once using `withGlobalHooks()` on the builder:

```typescript
const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .withGlobalHooks({
    onCreated: async ({ value, collection }) => {
      console.log(`[${collection.definition.name}] Created: ${value.id}`);
      return value;
    },
    onDeleted: async ({ value, collection }) => {
      console.log(`[${collection.definition.name}] Deleted: ${value.id}`);
      return true;
    },
  })
  .addCollection(Posts)
  .addCollection(Pages)
  .build();
```

Global hooks run **before** collection-specific hooks. Collection hooks can still override or cancel after the global hook runs.

***

## Context Injection

Use `withContext()` to inject dependencies (database connections, auth, config) into every hook:

```typescript
const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withContext(async () => {
    const db = await Database.connect();
    const auth = await getCurrentAuth();
    return { db, auth };
  })
  .addCollection(Posts)
  .build();

// Access in hooks
Posts.onCreated(async ({ value, context }) => {
  const { db, auth } = context as { db: Database; auth: Auth };
  await db.activityLog.insert({
    userId: auth.userId,
    action: 'post_created',
    documentId: value.id,
  });
  return value;
});
```

The context factory is called **fresh for every operation**, so you always have the latest state.

***

## Hook Execution Order

For a single operation, hooks execute in this order:

1. **Global hooks** (from `withGlobalHooks()`)
2. **Collection-specific hooks** (from `.onCreated()`, etc.)
3. **Adapter write/read**
4. **Event emission** (see [Events](/docs/collections/events))

If any hook returns `false`, the operation is **immediately cancelled** — no subsequent hooks run and no event is emitted.

***

## Real-World Example: CMS Publishing Workflow

```typescript
const Posts = IgniterCollectionModel.create('posts')
  .withSchema(postSchema)
  .onCreated(async ({ value }) => {
    // Auto-slug
    value.data.slug = slugify(value.title);
    return value;
  })
  .onUpdated(({ newValue, previousValue }) => {
    // Timestamp tracking
    if (newValue.data.published && !previousValue.data.published) {
      newValue.data.publishedAt = new Date().toISOString();
    }

    // Version bump
    newValue.data.version = (previousValue.data.version || 1) + 1;

    return newValue;
  })
  .onDeleted(({ value }) => {
    // Prevent deletion of published content
    return !value.data.published;
  })
  .onRead(({ value, context }) => {
    // Computed reading time
    value.data.readingTime = estimateReadingTime(value.content);
    return value;
  })
  .onList(({ values, context }) => {
    const { user } = context as { user: User };

    // Role-based filtering
    if (user.role === 'editor') {
      return values; // Editors see everything
    }

    return values.filter(v => v.data.published);
  })
  .build();
```

***

## Next Steps

<Cards>
  <Card title="Events" description="Subscribe to document lifecycle events globally or per-collection." href="/docs/collections/events" />

  <Card title="Views" description="Define data-driven views with component trees and actions." href="/docs/collections/views" />

  <Card title="Advanced" description="Context injection, telemetry, and advanced patterns." href="/docs/collections/advanced" />
</Cards>


---

# Introduction

> Type-safe ORM for content collections. Prisma-like API for Markdown, JSON, and YAML files with schema validation, lifecycle hooks, declarative views, and TypeScript-first configuration.
URL: https://igniterjs.com/docs/collections

## Overview

`@igniter-js/collections` is a type-safe ORM for content-driven applications. It gives you a **Prisma-like API** for working with Markdown, JSON, and YAML files — with full schema validation, lifecycle hooks, declarative views, and TypeScript autocomplete everywhere.

You define your content schema once using Zod, and collections infers the entire API surface. No code generation. No boilerplate. No surprises.

<Callout type="info">
  Collections works with **any filesystem adapter** — Node.js, Bun, Redis, or S3. The adapter pattern means you develop locally with the filesystem and deploy to distributed storage without changing a single line of collection code.
</Callout>

### Key Features

* **Prisma-like API** — `create`, `findUnique`, `findMany`, `update`, `delete`, `count` with full TypeScript inference
* **Schema Validation** — Zod schemas validate frontmatter at runtime, catching errors before files hit disk
* **Lifecycle Hooks** — `onCreated`, `onUpdated`, `onDeleted`, `onRead`, `onList` with cancel support (return `false`)
* **Rich Querying** — Filter operators (`gte`, `contains`, `has`), dot-notation nested access, full-text search
* **Declarative Views** — Define data hooks, component trees, and actions in pure TypeScript
* **Event System** — Subscribe to global (`created`) or scoped (`posts:updated`) events
* **Auto-Discovery** — Watch directories for `.schema.{ts,json}` and `.view.{ts,json}` files with hot reload
* **Context Injection** — Inject dependencies (DB connections, auth) into every hook and view
* **Multi-Adapter** — Node FS, Bun FS, Redis, S3, or build your own

***

## Architecture

Collections follows the **adapter pattern** — the same pattern used across the Igniter.js ecosystem. The manager layer handles CRUD, hooks, events, and validation. The adapter layer handles reading and writing files.

```mermaid
graph TD
    A[Your Application] --> B[IgniterCollectionsManager]
    B --> C[Collection Managers]
    C --> D[Hooks & Validation]
    B --> E[Event Emitter]
    B --> F[View Manager]
    B --> G[Schema Registry]
    C --> H[Adapter Interface]
    H --> I[NodeFsAdapter]
    H --> J[BunFsAdapter]
    H --> K[RedisAdapter]
    H --> L[S3Adapter]
```

Every operation flows through the same pipeline: **validate → execute hooks → write/read via adapter → emit events**.

***

## Quick Start

Get a type-safe content collection running in under two minutes.

<Steps>
  <Step>
    ### Install

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        npm install @igniter-js/collections zod
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @igniter-js/collections zod
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @igniter-js/collections zod
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @igniter-js/collections zod
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Define a Collection

    Create a schema and collection definition:

    ```typescript
    import { IgniterCollections, IgniterCollectionModel } from '@igniter-js/collections';
    import { NodeFsAdapter } from '@igniter-js/collections/adapters';
    import { z } from 'zod';

    const Posts = IgniterCollectionModel.create('posts')
      .withPatterns(['.content/posts/{id}.mdx'])
      .withSchema(z.object({
        title: z.string(),
        description: z.string(),
        published: z.boolean().default(false),
        tags: z.array(z.string()).optional(),
        author: z.string(),
      }))
      .build();
    ```
  </Step>

  <Step>
    ### Create the Manager

    Wire everything together with the builder:

    ```typescript
    const docs = IgniterCollections.create()
      .withAdapter(new NodeFsAdapter())
      .withBasePath(process.cwd())
      .addCollection(Posts)
      .build();
    ```
  </Step>

  <Step>
    ### Use It

    ```typescript
    // Create a post
    const post = await docs.posts.create({
      data: {
        title: 'Getting Started with Igniter.js',
        description: 'Learn how to build type-safe content apps',
        published: true,
        tags: ['tutorial', 'typescript'],
        author: 'Felipe Barcelos',
      }
    });

    console.log('Created:', post.id);
    // Created: 9f3e4d2a-8b7c-4e1f-a3d2-9c8b7e6f5a4d

    // Query with full type safety
    const published = await docs.posts.findMany({
      where: { published: true },
      orderBy: { createdAt: 'desc' as const },
    });
    ```
  </Step>
</Steps>

**You now have a type-safe, validated content store.** Every `create`, `update`, and `findMany` call is fully typed — IntelliSense knows your schema fields, and Zod validates every write.

***

## Core Concepts

<Accordions>
  <Accordion title="Collection Definition">
    A **collection** is a named group of documents with a shared schema and file pattern. You define it once using the builder pattern, and collections infers TypeScript types from your Zod schema.

    ```typescript
    const Posts = IgniterCollectionModel.create('posts')
      .withPatterns(['.content/posts/{id}.mdx'])
      .withSchema(z.object({ title: z.string(), published: z.boolean() }))
      .build();
    ```

    The collection name (`posts`) becomes the accessor on the manager (`docs.posts`).
  </Accordion>

  <Accordion title="CRUD Operations">
    Every collection supports the full CRUD surface:

    * **`create(args)`** — Create a document with validated frontmatter
    * **`findUnique(args)`** — Find a single document by ID or criteria
    * **`findMany(args?)`** — Query multiple documents with filters, sorting, and pagination
    * **`update(args)`** — Update document data (partial updates supported)
    * **`delete(args)`** — Delete a document permanently
    * **`count(args?)`** — Count documents matching criteria

    All operations are fully typed — your Zod schema drives the TypeScript inference.
  </Accordion>

  <Accordion title="Lifecycle Hooks">
    Intercept every operation with hooks that can modify, enrich, or cancel the operation:

    ```typescript
    const Posts = IgniterCollectionModel.create('posts')
      .withSchema(postSchema)
      .onCreated(async ({ value }) => {
        await notifySubscribers(value);
        return value; // proceed
      })
      .onUpdated(({ newValue, previousValue }) => {
        if (newValue.data.published && !previousValue.data.published) {
          newValue.data.publishedAt = new Date().toISOString();
        }
        return newValue;
      })
      .build();
    ```

    Return `false` from any hook to cancel the operation.
  </Accordion>

  <Accordion title="Events">
    Subscribe to document lifecycle events globally or scoped to a single collection:

    ```typescript
    // Global events
    const { off } = docs.on('created', ({ collection, value }) => {
      console.log(`Document created in ${collection}: ${value.id}`);
    });

    // Scoped events
    docs.on('posts:updated', ({ newValue, previousValue }) => {
      console.log(`Post ${newValue.id} updated`);
    });
    ```
  </Accordion>

  <Accordion title="Views">
    Define data-driven views with component trees, data hooks, and actions:

    ```typescript
    import { IgniterCollectionView } from '@igniter-js/collections';

    const DashboardView = IgniterCollectionView.create('dashboard')
      .withTitle('Analytics Dashboard')
      .withData(async ({ manager }) => {
        const posts = await manager.posts.findMany();
        return { posts, total: posts.length };
      })
      .withTree([
        { component: 'Metric', valuePath: '/total' },
        { component: 'Table', valuePath: '/posts' },
      ])
      .build();
    ```
  </Accordion>
</Accordions>

***

## Real-World Use Cases

Collections powers content-driven applications across many domains:

| Use Case                     | Description                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------ |
| **Documentation Sites**      | Manage docs as Markdown files with validated frontmatter and auto-discovered schemas       |
| **Blog Platforms**           | Store posts with draft/published workflows via hooks, full-text search, and tag filtering  |
| **CMS Backends**             | Build headless CMS with collections as the content store and views as the API layer        |
| **Configuration Management** | Validate and query config files with type-safe access and change events                    |
| **E-commerce Catalogs**      | Manage product listings with nested sub-collections for variants, reviews, and inventory   |
| **Multi-tenant Systems**     | Isolate tenant data with adapter routing and context injection for tenant-specific storage |

***

## Next Steps

<Cards>
  <Card title="Installation" description="Set up collections in your project with the right adapter for your runtime." href="/docs/collections/installation" />

  <Card title="Defining Collections" description="Learn schema definition, file patterns, sub-collections, and templates." href="/docs/collections/defining-collections" />

  <Card title="CRUD Operations" description="Master create, read, update, delete, and count with full type safety." href="/docs/collections/crud-operations" />

  <Card title="Querying" description="Filter with operators, sort, paginate, select fields, and full-text search." href="/docs/collections/querying" />
</Cards>


---

# Installation

> Install and configure @igniter-js/collections for your runtime. Choose the right adapter and set up your first collection in minutes.
URL: https://igniterjs.com/docs/collections/installation

## Installation

`@igniter-js/collections` works on **Node.js 18+** and **Bun 1.0+**. It requires `zod` (or any StandardSchemaV1-compatible validator) as a peer dependency.

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/collections zod
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/collections zod
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/collections zod
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/collections zod
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **Zod is the recommended schema library.** Collections uses the [StandardSchemaV1](https://github.com/standard-schema/standard-schema) interface, so any compatible validator (Valibot, ArkType) works, but Zod has first-class testing and the best inference story.
</Callout>

***

## Choosing an Adapter

The adapter determines where your files are stored. Collections ships with five adapters, each optimized for a specific use case:

| Adapter             | Import Path                        | Best For                                       |
| ------------------- | ---------------------------------- | ---------------------------------------------- |
| **NodeFsAdapter**   | `@igniter-js/collections/adapters` | Node.js server-side apps, local development    |
| **BunFsAdapter**    | `@igniter-js/collections/adapters` | Bun-native apps (uses `Bun.file`, `Bun.write`) |
| **BunRedisAdapter** | `@igniter-js/collections/adapters` | Distributed systems, multi-process apps        |
| **BunS3Adapter**    | `@igniter-js/collections/adapters` | Production deployments, object storage         |
| **MockAdapter**     | `@igniter-js/collections/adapters` | Testing and CI environments                    |

### Quick Adapter Setup

<Tabs items={['Node.js', 'Bun FS', 'Redis', 'S3', 'Mock']}>
  <Tab value="Node.js">
    ```typescript
    import { NodeFsAdapter } from '@igniter-js/collections/adapters';

    const adapter = new NodeFsAdapter();
    ```
  </Tab>

  <Tab value="Bun FS">
    ```typescript
    import { BunFsAdapter } from '@igniter-js/collections/adapters';

    const adapter = new BunFsAdapter();
    ```
  </Tab>

  <Tab value="Redis">
    ```typescript
    import { BunRedisAdapter } from '@igniter-js/collections/adapters';

    const adapter = new BunRedisAdapter({
      url: process.env.REDIS_URL,
      // Optional: key prefix for namespacing
      prefix: 'collections:',
    });
    ```
  </Tab>

  <Tab value="S3">
    ```typescript
    import { BunS3Adapter } from '@igniter-js/collections/adapters';

    const adapter = new BunS3Adapter({
      bucket: 'my-content-bucket',
      region: 'us-east-1',
      credentials: {
        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
      },
    });
    ```
  </Tab>

  <Tab value="Mock">
    ```typescript
    import { IgniterCollectionMockAdapter } from '@igniter-js/collections/adapters';

    const adapter = new IgniterCollectionMockAdapter();
    // All data stored in memory — perfect for tests
    ```
  </Tab>
</Tabs>

***

## Runtime Requirements

### Node.js

```json title="package.json"
{
  "engines": {
    "node": ">=18.0.0"
  }
}
```

The `NodeFsAdapter` uses `node:fs/promises`, `node:path`, and `fast-glob`. No native addons required.

### Bun

```json title="package.json"
{
  "engines": {
    "bun": ">=1.0.0"
  }
}
```

The `BunFsAdapter` uses `Bun.file`, `Bun.write`, and `Bun.Glob` for maximum performance. **No Node.js APIs** — pure Bun runtime.

<Callout type="warn">
  **Bun adapter exclusivity:** `BunFsAdapter`, `BunRedisAdapter`, and `BunS3Adapter` rely on Bun-native APIs and will not work in Node.js. Use `NodeFsAdapter` for Node.js environments.
</Callout>

***

## TypeScript Configuration

Collections requires TypeScript 5.6+ for full type inference. Ensure your `tsconfig.json` includes:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": "ES2022"
  }
}
```

The `"bundler"` module resolution is required for the `@igniter-js/collections/adapters` sub-path imports to resolve correctly.

***

## Verifying Installation

Create a minimal script to verify everything works:

```typescript title="verify.ts"
import { IgniterCollections, IgniterCollectionModel } from '@igniter-js/collections';
import { NodeFsAdapter } from '@igniter-js/collections/adapters';
import { z } from 'zod';

const Test = IgniterCollectionModel.create('test')
  .withPatterns(['.content/test/{id}.mdx'])
  .withSchema(z.object({ message: z.string() }))
  .build();

const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .addCollection(Test)
  .build();

const result = await docs.test.create({
  data: { message: 'Installation verified!' }
});

console.log('✅ Collections is working:', result.id);
```

Run it:

```bash
npx tsx verify.ts
# ✅ Collections is working: a1b2c3d4-...
```

***

## Next Steps

<Cards>
  <Card title="Defining Collections" description="Learn schema definition, file patterns, sub-collections, and templates." href="/docs/collections/defining-collections" />

  <Card title="CRUD Operations" description="Master create, read, update, delete, and count with type safety." href="/docs/collections/crud-operations" />

  <Card title="Adapters" description="Deep dive into each adapter and how to build your own." href="/docs/collections/adapters" />
</Cards>


---

# Querying

> Filter with operators, sort, paginate, select fields, include sub-collections, and full-text search your content collections.
URL: https://igniterjs.com/docs/collections/querying

## Querying

Collections provides a Prisma-like query API for filtering, sorting, paginating, and searching documents. All queries are fully typed — your Zod schema drives the filter shape.

***

## Where Clause

The `where` clause accepts direct field values, filter operators, and dot-notation for nested access.

### Direct Equality

The simplest filter: match fields exactly.

```typescript
// Find posts by a specific author
await docs.posts.findMany({
  where: { author: 'Felipe Barcelos' }
});

// Multiple conditions (AND logic)
await docs.posts.findMany({
  where: {
    published: true,
    author: 'Felipe Barcelos',
  }
});
```

### Filter by ID

```typescript
await docs.posts.findMany({
  where: { id: 'a1b2c3d4-...' }
});
```

***

## Scalar Filter Operators

For fields that are strings, numbers, or booleans, you can use operator objects instead of direct values.

| Operator     | Description               | Example                            |
| ------------ | ------------------------- | ---------------------------------- |
| `equals`     | Exact match               | `{ equals: 'hello' }`              |
| `not`        | Not equal                 | `{ not: 'draft' }`                 |
| `in`         | In array of values        | `{ in: ['tech', 'tutorial'] }`     |
| `notIn`      | Not in array              | `{ notIn: ['draft', 'archived'] }` |
| `lt`         | Less than                 | `{ lt: 100 }`                      |
| `lte`        | Less than or equal        | `{ lte: 100 }`                     |
| `gt`         | Greater than              | `{ gt: 0 }`                        |
| `gte`        | Greater than or equal     | `{ gte: 100 }`                     |
| `contains`   | Substring match (strings) | `{ contains: 'TypeScript' }`       |
| `startsWith` | Starts with (strings)     | `{ startsWith: 'Getting' }`        |
| `endsWith`   | Ends with (strings)       | `{ endsWith: 'Guide' }`            |

### Examples

```typescript
// Popular posts
await docs.posts.findMany({
  where: { views: { gte: 1000 } }
});

// Posts in specific categories
await docs.posts.findMany({
  where: { status: { in: ['published', 'featured'] } }
});

// Exclude drafts
await docs.posts.findMany({
  where: { status: { not: 'draft' } }
});

// Title search
await docs.posts.findMany({
  where: { title: { contains: 'TypeScript' } }
});

// Combined operators
await docs.posts.findMany({
  where: {
    views: { gte: 100, lt: 10000 },
    status: { not: 'draft' },
    title: { contains: 'caching' },
  }
});
```

***

## Array Filter Operators

For array fields (like `tags: string[]`), you can use array-specific operators.

| Operator   | Description                 | Example                                  |
| ---------- | --------------------------- | ---------------------------------------- |
| `has`      | Array contains value        | `{ has: 'featured' }`                    |
| `hasEvery` | Array contains all values   | `{ hasEvery: ['featured', 'tutorial'] }` |
| `hasSome`  | Array contains at least one | `{ hasSome: ['tech', 'programming'] }`   |
| `isEmpty`  | Array is empty or not       | `{ isEmpty: false }`                     |
| `length`   | Array length equals         | `{ length: 3 }`                          |

### Examples

```typescript
// Posts tagged 'featured'
await docs.posts.findMany({
  where: { tags: { has: 'featured' } }
});

// Posts with both 'featured' AND 'tutorial'
await docs.posts.findMany({
  where: { tags: { hasEvery: ['featured', 'tutorial'] } }
});

// Posts with any of these categories
await docs.posts.findMany({
  where: { categories: { hasSome: ['tech', 'programming', 'devops'] } }
});

// Posts that have comments (non-empty array)
await docs.posts.findMany({
  where: { comments: { isEmpty: false } }
});
```

***

## Nested Field Access (Dot Notation)

Access nested object fields using dot notation — no need for nested where objects.

```typescript
// Schema with nested objects
const Posts = IgniterCollectionModel.create('posts')
  .withSchema(z.object({
    title: z.string(),
    author: z.object({
      name: z.string(),
      email: z.string(),
      social: z.object({
        twitter: z.string().optional(),
        github: z.string().optional(),
      }).optional(),
    }),
  }))
  .build();
```

```typescript
// Access nested fields directly
await docs.posts.findMany({
  where: {
    'author.name': 'Felipe Barcelos',
    'author.social.twitter': { contains: '@' },
  }
});
```

***

## Ordering

Sort results by any schema field, `id`, `createdAt`, or `updatedAt`.

```typescript
// Newest first
await docs.posts.findMany({
  orderBy: { createdAt: 'desc' as const },
});

// Alphabetical
await docs.posts.findMany({
  orderBy: { title: 'asc' as const },
});

// Most viewed
await docs.posts.findMany({
  orderBy: { views: 'desc' as const },
});
```

***

## Pagination

Use `take` and `skip` for cursor-free pagination:

```typescript
// Page 1: first 10 posts
const page1 = await docs.posts.findMany({
  take: 10,
  skip: 0,
  orderBy: { createdAt: 'desc' as const },
});

// Page 2: next 10
const page2 = await docs.posts.findMany({
  take: 10,
  skip: 10,
  orderBy: { createdAt: 'desc' as const },
});

// Page 3
const page3 = await docs.posts.findMany({
  take: 10,
  skip: 20,
  orderBy: { createdAt: 'desc' as const },
});
```

***

## Field Selection

Control exactly which fields are returned.

### `select` — Whitelist

```typescript
// Return only specific fields
const titles = await docs.posts.findMany({
  select: { id: true, title: true, slug: true },
});
```

### `exclude` — Blacklist

```typescript
// Return everything except content
const summaries = await docs.posts.findMany({
  exclude: { content: true },
});
```

### Deep Selection

```typescript
const posts = await docs.posts.findMany({
  select: {
    id: true,
    title: true,
    author: {
      name: true,
      // email excluded
      social: { twitter: true },
    },
  },
});
```

<Callout type="warn">
  `select` and `exclude` are **mutually exclusive**. Use one or the other, never both in the same query.
</Callout>

***

## Full-Text Search

Collections includes a built-in full-text search engine powered by MiniSearch. Searches index title, description, tags, and content by default.

```typescript
const results = await docs.posts.findMany({
  where: {
    search: {
      term: 'TypeScript patterns',
    }
  }
});
```

### Search Options

| Option                  | Type                 | Default       | Description               |
| ----------------------- | -------------------- | ------------- | ------------------------- |
| `term`                  | `string \| string[]` | required      | Search terms              |
| `fields`                | `SearchFields`       | Common fields | Which fields to index     |
| `threshold`             | `number` (0-1)       | `0.2`         | Minimum relevance score   |
| `fuzzy`                 | `boolean`            | `false`       | Enable fuzzy matching     |
| `includeSubCollections` | `boolean`            | `false`       | Search in sub-collections |

### Targeted Field Search

```typescript
const results = await docs.posts.findMany({
  where: {
    search: {
      term: 'TypeScript',
      fields: {
        title: { weight: 2 }, // Title matches count 2x
        description: { weight: 1 },
        tags: { weight: 1.5 },
      },
      threshold: 0.3,
      fuzzy: true, // Handle typos
    }
  }
});
```

### Combined Search + Filters

```typescript
const results = await docs.posts.findMany({
  where: {
    published: true,
    search: { term: 'caching strategies' },
  },
  orderBy: { createdAt: 'desc' as const },
  take: 20,
});
```

***

## Including Sub-Collections

When a collection has sub-collections, you can include them in the query results:

```typescript
// Include comments with each post
const postsWithComments = await docs.posts.findMany({
  include: {
    comments: true,
  },
  take: 10,
});

// Include with filtering
const postsWithApproved = await docs.posts.findMany({
  include: {
    comments: {
      where: { approved: true },
      orderBy: { createdAt: 'desc' as const },
      take: 5,
    },
  },
});
```

***

## Real-World Example: Search Page

A complete blog search page with full-text search, tag filtering, and pagination:

```typescript
async function searchPosts(query: string, page = 1, pageSize = 20) {
  const filters: any = { published: true };

  // Full-text search when query is provided
  if (query) {
    filters.search = {
      term: query,
      fields: {
        title: { weight: 2 },
        description: { weight: 1 },
        tags: { weight: 1.5 },
      },
      fuzzy: true,
      threshold: 0.2,
    };
  }

  const [posts, total] = await Promise.all([
    docs.posts.findMany({
      where: filters,
      orderBy: { createdAt: 'desc' as const },
      take: pageSize,
      skip: (page - 1) * pageSize,
      select: {
        id: true,
        title: true,
        slug: true,
        excerpt: true,
        tags: true,
        author: true,
        createdAt: true,
      },
    }),
    docs.posts.count({ where: filters }),
  ]);

  return {
    posts,
    total,
    page,
    pageSize,
    totalPages: Math.ceil(total / pageSize),
  };
}

// Usage
const result = await searchPosts('TypeScript patterns', 1, 20);
console.log(`Found ${result.total} posts, showing page ${result.page}`);
```

***

## Next Steps

<Cards>
  <Card title="Hooks" description="Add lifecycle hooks for validation, enrichment, and cancellation." href="/docs/collections/hooks" />

  <Card title="Events" description="Subscribe to document lifecycle events globally or per-collection." href="/docs/collections/events" />

  <Card title="Views" description="Define data-driven views with component trees and actions." href="/docs/collections/views" />
</Cards>


---

# Troubleshooting

> Common errors, error codes, debugging strategies, and solutions for @igniter-js/collections.
URL: https://igniterjs.com/docs/collections/troubleshooting

## Troubleshooting

Solutions for common issues when working with collections.

***

## Common Errors

### `ADAPTER_REQUIRED`

**Error:** `Adapter is required. Use .withAdapter() to configure.`

**Cause:** `build()` was called without an adapter.

**Fix:**

```typescript
// ❌ Missing adapter
const docs = IgniterCollections.create()
  .addCollection(Posts)
  .build();

// ✅ Add an adapter
const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .addCollection(Posts)
  .build();
```

***

### `VALIDATION_ERROR`

**Error:** `Validation failed: Title is required`

**Cause:** Data doesn't match the Zod schema.

**Fix:** Check your schema and data:

```typescript
// ❌ Missing required field
await docs.posts.create({
  data: { description: 'No title here' }
  // Missing: title
});

// ✅ Include all required fields
await docs.posts.create({
  data: {
    title: 'My Post',
    description: 'With a title',
    author: 'Felipe',
  }
});
```

**Debugging:** The error `details` property includes the full Zod issue array:

```typescript
} catch (error) {
  if (error instanceof IgniterCollectionError) {
    console.log(error.details.issues);
    // [{ path: ['title'], message: 'Title is required' }]
  }
}
```

***

### `DOCUMENT_NOT_FOUND`

**Error:** `Document not found: {id}`

**Cause:** The document ID doesn't exist.

**Fix:**

```typescript
// ❌ Using a non-existent ID
const post = await docs.posts.findUnique({
  where: { id: 'non-existent-id' }
});
// post is null — not an error

// ❌ Using update/delete with non-existent ID
await docs.posts.update({
  where: { id: 'non-existent-id' },
  data: { title: 'New' }
});
// Throws DOCUMENT_NOT_FOUND

// ✅ Check existence first
const exists = await docs.posts.findUnique({
  where: { id: 'my-id' }
});
if (exists) {
  await docs.posts.update({
    where: { id: 'my-id' },
    data: { title: 'New' },
  });
}
```

***

### `HOOK_CANCELLED`

**Error:** `Document creation cancelled by hook`

**Cause:** A hook returned `false`, cancelling the operation.

**Fix:** Check your hook logic:

```typescript
// ❌ Hook always cancels
.onCreated(({ value }) => {
  return false; // Never creates anything
})

// ✅ Conditional cancellation
.onCreated(({ value }) => {
  if (value.data.title.length < 3) {
    return false; // Cancel short titles
  }
  return value;
})
```

***

### `PARSE_ERROR`

**Error:** `Failed to parse document: {id}`

**Cause:** The markdown file has malformed frontmatter or invalid YAML.

**Fix:**

```yaml
# ❌ Malformed frontmatter
---
title: "Unclosed quote
published: true
---

# ❌ Invalid YAML
---
title: Hello
  indented: wrong
---
```

```yaml
# ✅ Correct frontmatter
---
title: My Post
published: true
tags:
  - typescript
  - tutorial
---
```

***

### `VIEW_NOT_FOUND` / `ACTION_NOT_FOUND`

**Error:** `View "{name}" not found` or `Action "{name}" not found`

**Cause:** View or action was not registered.

**Fix:**

```typescript
// ❌ Rendering unregistered view
await docs.views.render('nonexistent');

// ✅ Register views before use
const view = IgniterCollectionView.create('dashboard')
  .withData(async ({ manager }) => ({ items: [] }))
  .build();

const docs = IgniterCollections.create()
  .withAdapter(adapter)
  .addView(view)
  .build();

await docs.views.render('dashboard'); // ✅ Works
```

***

## TypeScript Issues

### Missing Type Inference

**Problem:** Collection methods return `any` or generic types.

**Solutions:**

1. Ensure `strict: true` in `tsconfig.json`
2. Make sure you use `z.object()` (not `z.any()` or `z.unknown()`)
3. Use `as const` for `orderBy` values:
   ```typescript
   // ❌ 'string' not assignable to 'asc' | 'desc'
   orderBy: { createdAt: 'desc' }

   // ✅ Use as const
   orderBy: { createdAt: 'desc' as const }
   ```

### Module Resolution Errors

**Problem:** `Cannot find module '@igniter-js/collections/adapters'`

**Fix:** Set `moduleResolution: "bundler"` in `tsconfig.json`:

```json
{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}
```

***

## Adapter Issues

### File Not Found After Creation

**Problem:** Document created but file doesn't appear on disk.

**Debug:**

```typescript
const post = await docs.posts.create({ data: { title: 'Test' } });
console.log(post.path); // Check the resolved path
```

**Common causes:**

* `basePath` not set to the expected root
* Pattern doesn't resolve to expected directory
* File was written but to a different location

### S3 Access Denied

**Problem:** `AccessDenied` when using `BunS3Adapter`.

**Fix:** Verify:

1. IAM policy includes `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, `s3:ListBucket`
2. Bucket exists in the specified region
3. Credentials have not expired

***

## Performance

### Slow `findMany` with Large Collections

**Solutions:**

* Always use `take` for pagination: `findMany({ take: 20, skip: 0 })`
* Use `select` to return only needed fields
* Add `where` filters to narrow the result set
* For full-text search, lower the `threshold` or narrow `fields`

### Memory Usage with `findMany`

**Problem:** Loading thousands of documents into memory.

**Solution:** Always paginate:

```typescript
// ❌ Loads everything
const allPosts = await docs.posts.findMany();

// ✅ Paginate
const page = await docs.posts.findMany({ take: 50, skip: 0 });
```

***

## Next Steps

<Cards>
  <Card title="Best Practices" description="Patterns, anti-patterns, and production tips." href="/docs/collections/best-practices" />

  <Card title="Framework Integration" description="Next.js, Express, Astro, and Remix examples." href="/docs/collections/framework-integration" />

  <Card title="API Reference" description="Complete reference for all builders and managers." href="/docs/collections/api-reference" />
</Cards>


---

# Views

> Define data-driven views with component trees, data hooks, and executable actions. Build dashboards, tables, and analytics in pure TypeScript.
URL: https://igniterjs.com/docs/collections/views

## Views

Views are first-class, global objects that define how data is fetched, rendered, and interacted with. They live alongside collections and have unrestricted access to the full manager via the `withData` hook.

***

## View Anatomy

A view has four core parts:

```typescript
import { IgniterCollectionView } from '@igniter-js/collections';

const DashboardView = IgniterCollectionView.create('dashboard')
  .withTitle('Analytics Dashboard')           // Display title
  .withDescription('Key metrics and KPIs')     // Description
  .withMetadata({ icon: 'chart', order: 1 })   // UI metadata
  .withData(async ({ manager }) => {           // Data hook
    const posts = await manager.posts.findMany();
    return { posts, total: posts.length };
  })
  .withTree([                                   // Component tree
    { component: 'Metric', valuePath: '/total' },
    { component: 'Table', valuePath: '/posts' },
  ])
  .addAction('export', {                        // Actions
    description: 'Export to CSV',
    handler: async ({ manager, params }) => ({ success: true }),
  })
  .build();
```

***

## The Data Hook (`withData`)

The heart of every view. Receives the full `IIgniterCollectionsManager` and returns any data shape you need:

```typescript
.withData(async ({ manager }) => {
  const [posts, pages, authors] = await Promise.all([
    manager.posts.findMany({ where: { published: true }, take: 10 }),
    manager.pages.findMany({ take: 20 }),
    manager.authors.count(),
  ]);

  return {
    recentPosts: posts,
    pages,
    authorCount: authors,
    lastUpdated: new Date().toISOString(),
  };
})
```

The returned object becomes the data context for the component tree. The `valuePath` in each tree node references paths within this data object.

***

## The Component Tree (`withTree`)

The component tree defines the UI structure. Each node has a `component` name and a `valuePath` that binds to data:

```typescript
.withTree([
  {
    component: 'Section',
    title: 'Overview',
    children: [
      { component: 'Metric', valuePath: '/totalPosts', title: 'Total Posts' },
      { component: 'Metric', valuePath: '/totalPages', title: 'Pages' },
      { component: 'Metric', valuePath: '/totalAuthors', title: 'Authors' },
    ],
  },
  {
    component: 'Section',
    title: 'Recent Posts',
    children: [
      { component: 'Table', valuePath: '/recentPosts' },
    ],
  },
])
```

<Callout type="info">
  Component names map to the centralized Fractal view component registry. Use `fractal views components` to list all available components and their accepted props.
</Callout>

***

## Actions (`addAction`)

Actions are executable functions bound to a view. They receive the manager, request params, and optional user context:

```typescript
const DashboardView = IgniterCollectionView.create('dashboard')
  .withData(async ({ manager }) => {
    const posts = await manager.posts.findMany({ take: 50 });
    return { posts, total: posts.length };
  })
  .addAction('export', {
    description: 'Export posts to CSV',
    handler: async ({ manager, params }) => {
      const { format = 'csv' } = params as { format?: string };
      const posts = await manager.posts.findMany();

      if (format === 'csv') {
        const csv = convertToCSV(posts);
        return { success: true, data: csv, contentType: 'text/csv' };
      }

      return { success: true, data: posts, contentType: 'application/json' };
    },
  })
  .addAction('publishAll', {
    description: 'Publish all draft posts',
    handler: async ({ manager }) => {
      const drafts = await manager.posts.findMany({
        where: { published: false },
      });

      for (const draft of drafts) {
        await manager.posts.update({
          where: { id: draft.id },
          data: { published: true },
        });
      }

      return { success: true, count: drafts.length };
    },
  })
  .build();
```

### Action Context

| Field     | Type                         | Description                               |
| --------- | ---------------------------- | ----------------------------------------- |
| `manager` | `IIgniterCollectionsManager` | Full access to all collections            |
| `params`  | `Record<string, unknown>`    | Parameters from the action call           |
| `context` | `unknown`                    | User-defined context from `withContext()` |

***

## Rendering Views

Views are registered on the manager and can be rendered programmatically:

```typescript
const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .addCollection(Posts)
  .addView(DashboardView)
  .build();

// Render a view
const result = await docs.views.render('dashboard');

console.log(result.data);   // { posts: [...], total: 42 }
console.log(result.tree);   // Component tree nodes
console.log(result.meta);   // { title, description, metadata }

// Execute an action
const actionResult = await docs.views.execute('dashboard', 'export', {
  format: 'csv',
});
```

***

## Programmatic vs Watched Views

Views can be defined two ways:

### Programmatic (Builder API)

```typescript
const view = IgniterCollectionView.create('dashboard')
  .withData(async ({ manager }) => ({ items: [] }))
  .build();

docs.addView(view);
```

### File-Based (Auto-Discovery)

```typescript
// .fractal/views/dashboard.view.ts
export default {
  name: 'dashboard',
  title: 'Dashboard',
  getData: async ({ manager }) => {
    const posts = await manager.posts.findMany();
    return { posts };
  },
  tree: [{ component: 'Table', valuePath: '/posts' }],
};
```

```typescript
const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withWatcher('.fractal', { views: '*.view.{ts,json}' })
  .build();

// Views auto-discovered from .fractal/views/*.view.ts
```

Programmatic views take precedence over watched views when there's a name conflict.

***

## Real-World Example: Content Dashboard

```typescript
const ContentDashboard = IgniterCollectionView.create('content-dashboard')
  .withTitle('Content Dashboard')
  .withDescription('Overview of all content across collections')
  .withMetadata({ icon: 'layout-dashboard', order: 1 })
  .withData(async ({ manager }) => {
    const [posts, pages, drafts, featuredPosts] = await Promise.all([
      manager.posts.findMany({
        orderBy: { createdAt: 'desc' as const },
        take: 10,
        select: { id: true, title: true, author: true, published: true, createdAt: true },
      }),
      manager.pages.count(),
      manager.posts.count({ where: { published: false } }),
      manager.posts.findMany({
        where: { published: true, featured: true },
        take: 5,
      }),
    ]);

    return {
      totalPosts: await manager.posts.count(),
      totalPages: pages,
      draftCount: drafts,
      recentPosts: posts,
      featuredPosts,
      lastUpdated: new Date().toISOString(),
    };
  })
  .withTree([
    {
      component: 'Section',
      title: 'Overview',
      children: [
        { component: 'Metric', valuePath: '/totalPosts', title: 'Total Posts' },
        { component: 'Metric', valuePath: '/totalPages', title: 'Pages' },
        { component: 'Metric', valuePath: '/draftCount', title: 'Drafts', variant: 'warning' },
      ],
    },
    {
      component: 'Section',
      title: 'Featured Posts',
      children: [
        { component: 'Table', valuePath: '/featuredPosts' },
      ],
    },
    {
      component: 'Section',
      title: 'Recent Posts',
      children: [
        { component: 'Table', valuePath: '/recentPosts' },
      ],
    },
  ])
  .addAction('createPost', {
    description: 'Create a new draft post',
    handler: async ({ manager, params }) => {
      const { title, author } = params as { title: string; author: string };
      const post = await manager.posts.create({
        data: {
          title,
          author,
          published: false,
          tags: [],
        },
      });
      return { success: true, post };
    },
  })
  .build();
```

***

## Next Steps

<Cards>
  <Card title="Adapters" description="Choose the right storage adapter for your environment." href="/docs/collections/adapters" />

  <Card title="Watcher" description="Auto-discover schemas and views with file watching." href="/docs/collections/watcher" />

  <Card title="Advanced" description="Context injection, telemetry, and global hooks." href="/docs/collections/advanced" />
</Cards>


---

# File Watcher

> Auto-discover collections and views from schema and view files. Enable hot reload for instant feedback during development.
URL: https://igniterjs.com/docs/collections/watcher

## File Watcher

The watcher auto-discovers collections and views from `.schema` and `.view` files on disk. Configure it once, and collections automatically picks up new schemas and views as you create them — no restart required.

***

## How It Works

1. On `build()`, the watcher scans configured directories for `.schema.{ts,json}` and `.view.{ts,json}` files
2. Discovered schemas become collection managers (alongside programmatic ones)
3. Discovered views are merged with programmatic views
4. If `autoWatch: true`, the watcher monitors for file changes and reloads automatically

```mermaid
graph LR
    A[Schema Files] --> C[Schema Registry]
    B[View Files] --> D[View Registry]
    C --> E[Collection Managers]
    D --> F[View Manager]
    E --> G[docs.posts / docs.pages]
    F --> H[docs.views.render]
```

***

## Configuration

Enable the watcher on the builder with the directory path and optional configuration:

```typescript
const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .withWatcher('.fractal', {
    collections: '*.schema.{json,ts}',
    views: '*.view.{json,ts}',
    autoWatch: true, // Enable hot reload
  })
  .addCollection(Posts) // Programmatic collections still work
  .build();
```

### Options

| Option               | Type                 | Default                | Description                      |
| -------------------- | -------------------- | ---------------------- | -------------------------------- |
| `paths` (positional) | `string \| string[]` | required               | Directory or directories to scan |
| `collections`        | `string`             | `"*.schema.{json,ts}"` | Glob pattern for schema files    |
| `views`              | `string`             | `"*.view.{json,ts}"`   | Glob pattern for view files      |
| `autoWatch`          | `boolean`            | `false`                | Start watching immediately       |

### Multiple Directories

```typescript
.withWatcher(['.fractal', '.content/schemas'], {
  autoWatch: true,
})
```

***

## Schema Files

Schema files define collections declaratively. They can be JSON or TypeScript.

### JSON Schema File

```json title=".fractal/posts.schema.json"
{
  "name": "posts",
  "patterns": [".content/posts/{id}.mdx"],
  "schema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "published": { "type": "boolean", "default": false },
      "tags": { "type": "array", "items": { "type": "string" } },
      "author": { "type": "string" }
    },
    "required": ["title", "author"]
  }
}
```

### TypeScript Schema File

```typescript title=".fractal/posts.schema.ts"
import { z } from 'zod';

export default {
  name: 'posts',
  patterns: ['.content/posts/{id}.mdx'],
  schema: z.object({
    title: z.string(),
    published: z.boolean().default(false),
    tags: z.array(z.string()).optional(),
    author: z.string(),
  }),
};
```

<Callout type="info">
  **TypeScript schemas provide better IntelliSense** and full Zod validation. JSON schemas are compatible with any tool that produces standard JSON Schema.
</Callout>

***

## View Files

Views can also be auto-discovered from `.view` files.

```typescript title=".fractal/dashboard.view.ts"
import type { IgniterCollectionViewDataHook } from '@igniter-js/collections';

export default {
  name: 'dashboard',
  title: 'Analytics Dashboard',
  description: 'Key metrics overview',
  metadata: { icon: 'chart', order: 1 },
  getData: async ({ manager }) => {
    const posts = await manager.posts.findMany();
    return { posts, total: posts.length };
  },
  tree: [
    { component: 'Metric', valuePath: '/total' },
    { component: 'Table', valuePath: '/posts' },
  ],
};
```

***

## Manual Refresh

Call `refresh()` to reload schemas and views from disk on demand:

```typescript
// After creating new schema files programmatically
await docs.refresh();

// New collections are now available
const newPosts = await docs.posts.findMany();
```

<Callout type="info">
  `refresh()` merges discovered schemas with programmatic collections. Programmatic collections **always take precedence** in case of name conflicts.
</Callout>

***

## Watcher Control

Control the watcher at runtime:

```typescript
// Start watching
await docs.watcher.start();

// Check status
console.log(docs.watcher.isWatching); // true

// Stop watching
docs.watcher.stop();

console.log(docs.watcher.isWatching); // false
```

The watcher also exposes its status via `isWatching` (a read-only boolean property).

***

## Conflict Resolution

When a schema or view file has the same name as a programmatic definition, the programmatic version wins:

```typescript
const Posts = IgniterCollectionModel.create('posts')
  .withSchema(programmaticSchema)
  .build();

const docs = IgniterCollections.create()
  .withAdapter(adapter)
  .withWatcher('.fractal') // May also discover 'posts' schema
  .addCollection(Posts)    // Programmatic 'posts' takes precedence
  .build();
```

A warning is logged when conflicts occur: `View conflict: programmatic view "dashboard" overrides watched view`.

***

## Real-World Example: Plugins System

Use the watcher to build a plugin system where third-party code can register new content types:

```typescript
// Core app bootstrapping
const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .withWatcher('.fractal/plugins', {
    collections: '**/*.schema.ts',
    views: '**/*.view.ts',
    autoWatch: true,
  })
  .addCollection(CorePosts)   // Built-in collections
  .addCollection(CorePages)
  .build();

// Third-party plugin: .fractal/plugins/events/events.schema.ts
export default {
  name: 'events',
  patterns: ['.content/events/{id}.mdx'],
  schema: z.object({
    name: z.string(),
    date: z.string(),
    location: z.string(),
  }),
};

// Now accessible without any code changes
const events = await docs.events.findMany();
```

***

## Next Steps

<Cards>
  <Card title="Advanced" description="Context injection, telemetry, global hooks, and multi-pattern." href="/docs/collections/advanced" />

  <Card title="API Reference" description="Complete reference for all builders, managers, and types." href="/docs/collections/api-reference" />

  <Card title="Best Practices" description="Patterns, anti-patterns, and performance tips." href="/docs/collections/best-practices" />
</Cards>


---

# Actions

> Execute typed connector actions with input validation, error handling, and full TypeScript inference. Learn the action builder pattern, error codes, and patterns.
URL: https://igniterjs.com/docs/connectors/actions

## Actions

Actions are the **execution layer** of connectors. They validate input, run the handler, validate output, and emit telemetry events — all with full TypeScript inference.

***

## The Action Builder

Every action call follows a fluent builder pattern through `scoped.action()`:

```typescript
const { data, error } = await scoped
  .action("telegram", "sendMessage")
  .call({ message: "Hello!" });

// data: { messageId: string; timestamp: Date } | null
// error: Error | null
```

<Callout type="info">
  Actions **never throw** on handler errors. Instead, they return `{ data: null, error }`. Validation errors (bad input) and structural errors (connector not connected) **do throw** — catch them explicitly.
</Callout>

***

## Error Handling

There are two categories of errors when executing actions:

### 1. Structural Errors (throw)

These are thrown and should be caught:

```typescript
try {
  const { data, error } = await scoped
    .action("telegram", "sendMessage")
    .call({ message: "Hi!" });
} catch (err) {
  if (IgniterConnectorError.isConnectorError(err)) {
    // CONNECTOR_NOT_FOUND      — connector key not registered
    // CONNECTOR_NOT_CONNECTED  — not connected for this scope
    // CONNECTOR_ACTION_NOT_FOUND — action key not found
    // CONNECTOR_ACTION_INPUT_INVALID — input validation failed
    // CONNECTOR_DISABLED       — connector is disabled
  }
}
```

### 2. Handler Errors (returned)

Handler errors are returned in the `error` field:

```typescript
const { data, error } = await scoped
  .action("telegram", "sendMessage")
  .call({ message: "Hi!" });

if (error) {
  // Handler threw an error — your handler's exception
  console.error("Action failed:", error.message);
  return { status: 500, error: error.message };
}

// Safe to use data
console.log("Message ID:", data?.messageId);
```

### Full Error Handling Pattern

```typescript
import { IgniterConnectorError } from "@igniter-js/connectors";

async function safeAction(scoped, connector, action, input) {
  try {
    const { data, error } = await scoped
      .action(connector, action)
      .call(input);

    if (error) {
      return { success: false, error: error.message, code: "HANDLER_ERROR" };
    }

    return { success: true, data };
  } catch (err) {
    if (IgniterConnectorError.isConnectorError(err)) {
      return {
        success: false,
        error: err.message,
        code: err.code,
        statusCode: err.statusCode,
      };
    }
    throw err; // Re-throw unexpected errors
  }
}
```

***

## Type Inference

The action builder preserves all types from your connector definition:

```typescript
const telegram = IgniterConnector.create()
  .withConfig(z.object({ botToken: z.string(), chatId: z.string() }))
  .addAction("sendMessage", {
    input: z.object({ message: z.string() }),
    output: z.object({ messageId: z.string() }),
    handler: async ({ input, config }) => {
      // input.message — string (inferred from schema)
      // config.botToken — string (inferred from config schema)
      return { messageId: "123" };
    },
  })
  .build();

// Fully typed call
const { data } = await scoped
  .action("telegram", "sendMessage")
  .call({ message: "Hi" });
//       ^ input is typed: { message: string }
// data is typed: { messageId: string } | null
```

### Without Output Schema

If you omit the output schema, the return type is **inferred from your handler**:

```typescript
.addAction("getCount", {
  input: z.object({}),
  handler: async () => 42,
})

const { data } = await scoped.action("telegram", "getCount").call({});
// data: number | null
```

***

## Action Handler Context

The handler receives a rich context object:

```typescript
handler: async ({
  input,    // Validated action input
  config,   // Decrypted connector configuration
  context,  // From onContext hook (if defined)
  oauth,    // OAuth tokens (if OAuth connector)
  scope,    // Scope type (e.g., "organization")
  identity, // Scope identifier (e.g., "org_123")
}) => {
  // input.message — typed from input schema
  // config.botToken — typed from config schema
  // oauth?.accessToken — available for OAuth connectors
}
```

***

## Action Timing & Telemetry

When telemetry is enabled, actions automatically emit events:

| Event              | When                            |
| ------------------ | ------------------------------- |
| `action.started`   | Before handler execution        |
| `action.completed` | After successful handler return |
| `action.failed`    | After handler throws            |

Each event includes: connector key, action name, scope, identity, duration.

```typescript
// Telemetry events emitted automatically
const { data, error } = await scoped
  .action("telegram", "sendMessage")
  .call({ message: "Hi!" });
// → igniter.connectors.action.started
// → igniter.connectors.action.completed (duration: 245ms)
```

***

## Non-Scoped Actions

You can also execute actions directly from the manager (useful for system-level connectors):

```typescript
const { data, error } = await connectors
  .action("telegram", "sendMessage")
  .call({ message: "System notification" });
```

<Callout type="warn">
  Non-scoped actions bypass scope isolation. Only use for system connectors with `.withDefaultConfig()`.
</Callout>

***

## Framework Integration

### Next.js API Route

```typescript
// app/api/actions/[connector]/[action]/route.ts
export async function POST(req, { params }) {
  const scoped = connectors.scope("organization", getOrgId(req));
  const input = await req.json();

  try {
    const { data, error } = await scoped
      .action(params.connector, params.action)
      .call(input);

    if (error) return Response.json({ error: error.message }, { status: 500 });
    return Response.json(data);
  } catch (err) {
    if (IgniterConnectorError.isConnectorError(err)) {
      return Response.json(
        { error: err.message, code: err.code },
        { status: err.statusCode },
      );
    }
    return Response.json({ error: "Internal error" }, { status: 500 });
  }
}
```

### Express Route

```typescript
app.post("/api/:connector/:action", async (req, res) => {
  const { connector, action } = req.params;
  const scoped = connectors.scope("organization", req.orgId);

  try {
    const { data, error } = await scoped
      .action(connector, action)
      .call(req.body);

    if (error) return res.status(500).json({ error: error.message });
    res.json(data);
  } catch (err) {
    if (IgniterConnectorError.isConnectorError(err)) {
      return res.status(err.statusCode).json({
        error: err.message,
        code: err.code,
      });
    }
    res.status(500).json({ error: "Internal server error" });
  }
});
```

***

## Next Steps

* [Lifecycle Hooks](/docs/connectors/hooks) — Connect, disconnect, and error hooks
* [Events](/docs/connectors/events) — Subscribe to connector events
* [Troubleshooting](/docs/connectors/troubleshooting) — Common error codes and solutions


---

# Database Adapters

> Persist connector configurations with Prisma, in-memory storage for testing, or build your own custom adapter. The adapter interface and implementation guide.
URL: https://igniterjs.com/docs/connectors/adapters

## Database Adapters

Adapters are the **persistence layer** for connectors. They handle CRUD operations on connector configurations — storing scoped records, toggling enabled state, and tracking webhook metadata.

Connectors ships with two built-in adapters: **Prisma** for production and **Mock** for testing.

***

## Prisma Adapter

The Prisma adapter uses your existing Prisma schema to store connector configurations.

### Setup

```typescript
import { IgniterConnectorPrismaAdapter } from "@igniter-js/connectors/adapters";
import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

const connectors = IgniterConnectorManager.create()
  .withDatabase(IgniterConnectorPrismaAdapter.create(prisma))
  // ...
  .build();
```

### Prisma Schema

Add this model to your Prisma schema:

```prisma
model Connector {
  id        String   @id @default(cuid())
  scope     String
  identity  String
  provider  String
  value     Json
  enabled   Boolean  @default(true)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@unique([scope, identity, provider])
  @@index([provider])
}
```

### Custom Model Name

Override the default model name (`Connector`) if needed:

```typescript
.withDatabase(
  IgniterConnectorPrismaAdapter.create(prisma, { model: "Integration" })
)
```

### Supported Databases

The Prisma adapter works with any Prisma-supported database: PostgreSQL, MySQL, SQLite, SQL Server, CockroachDB, MongoDB.

***

## Mock Adapter

The mock adapter stores data **in memory** — perfect for testing, development, and CI environments:

```typescript
import { IgniterConnectorMockAdapter } from "@igniter-js/connectors/adapters";

const connectors = IgniterConnectorManager.create()
  .withDatabase(IgniterConnectorMockAdapter.create())
  // ...
  .build();
```

### Testing with Mock Adapter

```typescript
import { describe, it, expect, beforeEach } from "vitest";
import { IgniterConnectorManager } from "@igniter-js/connectors";
import { IgniterConnectorMockAdapter } from "@igniter-js/connectors/adapters";

describe("Telegram Integration", () => {
  let connectors;

  beforeEach(() => {
    connectors = IgniterConnectorManager.create()
      .withDatabase(IgniterConnectorMockAdapter.create())
      .addScope("organization", { required: true })
      .addConnector("telegram", telegramConnector)
      .build();
  });

  it("connects and sends a message", async () => {
    const scoped = connectors.scope("organization", "test-org");

    await scoped.connect("telegram", {
      botToken: "test-token",
      chatId: "test-chat",
    });

    const instance = await scoped.get("telegram");
    expect(instance).not.toBeNull();
    expect(instance?.enabled).toBe(true);
  });

  it("isolates scopes", async () => {
    const orgA = connectors.scope("organization", "org-a");
    const orgB = connectors.scope("organization", "org-b");

    await orgA.connect("telegram", { botToken: "a", chatId: "a" });
    await orgB.connect("telegram", { botToken: "b", chatId: "b" });

    const listA = await orgA.list();
    const listB = await orgB.list();
    expect(listA).toHaveLength(1);
    expect(listB).toHaveLength(1);

    expect(listA[0].config.chatId).toBe("a");
    expect(listB[0].config.chatId).toBe("b");
  });
});
```

***

## Custom Adapter

Implement the `IgniterConnectorAdapter` interface to create adapters for any database:

```typescript
import type { IgniterConnectorAdapter, IgniterConnectorRecord } from "@igniter-js/connectors";

class MyCustomAdapter implements IgniterConnectorAdapter {
  async get(scope: string, identity: string, provider: string) {
    // Fetch a single record
    return db.connectors.findFirst({
      where: { scope, identity, provider },
    });
  }

  async list(scope: string, identity: string) {
    // List all records for a scope/identity
    return db.connectors.findMany({
      where: { scope, identity },
      orderBy: { createdAt: "desc" },
    });
  }

  async save(scope, identity, provider, value, enabled) {
    // Upsert a record
    return db.connectors.upsert({
      where: { scope_identity_provider: { scope, identity, provider } },
      create: { scope, identity, provider, value, enabled },
      update: { value, enabled },
    });
  }

  async update(scope, identity, provider, data) {
    // Partial update
    return db.connectors.update({
      where: { scope_identity_provider: { scope, identity, provider } },
      data,
    });
  }

  async delete(scope, identity, provider) {
    await db.connectors.deleteMany({
      where: { scope, identity, provider },
    });
  }

  async exists(scope, identity, provider) {
    const count = await db.connectors.count({
      where: { scope, identity, provider },
    });
    return count > 0;
  }

  async countConnections(provider) {
    return db.connectors.count({ where: { provider } });
  }

  async findByWebhookSecret(provider, secret) {
    // Find by webhook secret stored in JSON value
    return db.connectors.findFirst({
      where: {
        provider,
        value: { path: ["webhook", "secret"], equals: secret },
      },
    });
  }

  async updateWebhookMetadata(provider, secret, metadata) {
    await db.connectors.updateMany({
      where: {
        provider,
        value: { path: ["webhook", "secret"], equals: secret },
      },
      data: {
        value: db.raw(`jsonb_set(value, '{webhook,lastEventAt}', ...)`),
      },
    });
  }
}
```

### Adapter Interface

| Method                                              | Description                          |
| --------------------------------------------------- | ------------------------------------ |
| `get(scope, identity, provider)`                    | Fetch a single connector record      |
| `list(scope, identity)`                             | List all records for scope+identity  |
| `save(scope, identity, provider, value, enabled)`   | Upsert a connector record            |
| `update(scope, identity, provider, data)`           | Partially update a record            |
| `delete(scope, identity, provider)`                 | Remove a record                      |
| `exists(scope, identity, provider)`                 | Check if record exists               |
| `countConnections(provider)`                        | Count all connections for a provider |
| `findByWebhookSecret(provider, secret)`             | Find record by webhook secret        |
| `updateWebhookMetadata(provider, secret, metadata)` | Update webhook tracking data         |

***

## Adapter Record Shape

Every adapter returns records with this shape:

```typescript
interface IgniterConnectorRecord {
  id: string;
  scope: string;       // Scope type (e.g., "organization")
  identity: string;    // Scope identifier (e.g., "org_123")
  provider: string;    // Connector key (e.g., "telegram")
  value: Record<string, unknown>;  // JSON config (may contain encrypted fields)
  enabled: boolean;    // Whether the connector is enabled
  createdAt: Date;
  updatedAt: Date;
}
```

***

## Next Steps

* [Manager Setup](/docs/connectors/manager-setup) — Wire adapters into the manager
* [Telemetry](/docs/connectors/telemetry) — Adapter operation telemetry
* [API Reference](/docs/connectors/api-reference) — Full adapter type reference


---

# API Reference

> Complete API reference for @igniter-js/connectors. All exports, builder methods, manager operations, scoped instance API, type helpers, and error codes.
URL: https://igniterjs.com/docs/connectors/api-reference

## API Reference

Complete reference for all public exports in `@igniter-js/connectors`.

***

## Main Exports

```typescript
import {
  // Core builders
  IgniterConnector,
  IgniterConnectorManager,
  IgniterConnectorManagerBuilder,

  // Error handling
  IgniterConnectorError,
  IGNITER_CONNECTOR_ERROR_CODES,

  // Utilities
  IgniterConnectorCrypto,
  IgniterConnectorFields,
  IgniterConnectorSchema,
  IgniterConnectorOAuthUtils,
  IgniterConnectorUrl,

  // Type helpers
  $Infer,
  $InferScoped,
  $InferConnectorKey,
  $InferScopeKey,
  $InferConfig,
  $InferActionKeys,
} from "@igniter-js/connectors";
```

### Subpath: `/adapters`

```typescript
import {
  IgniterConnectorBaseAdapter,
  IgniterConnectorPrismaAdapter,
  IgniterConnectorMockAdapter,
} from "@igniter-js/connectors/adapters";
```

### Subpath: `/telemetry`

```typescript
import {
  IgniterConnectorsTelemetryEvents,
} from "@igniter-js/connectors/telemetry";
```

***

## IgniterConnector

Static `create()` factory for building connector definitions.

### `IgniterConnector.create()`

Creates a new `IgniterConnectorBuilder` instance.

```typescript
const builder = IgniterConnector.create();
```

### Builder Methods

#### `.withConfig(schema)`

Defines the configuration schema. **Required.**

| Parameter | Type               | Description                                      |
| --------- | ------------------ | ------------------------------------------------ |
| `schema`  | `StandardSchemaV1` | Zod/Valibot/ArkType schema for config validation |

```typescript
.withConfig(z.object({
  apiKey: z.string().describe("API key"),
  webhookUrl: z.string().url().optional(),
}))
```

#### `.withMetadata(schema, value)`

Sets static metadata for UI rendering.

| Parameter | Type                 | Description           |
| --------- | -------------------- | --------------------- |
| `schema`  | `StandardSchemaV1`   | Schema for validation |
| `value`   | inferred from schema | Metadata value        |

```typescript
.withMetadata(
  z.object({ name: z.string(), icon: z.string() }),
  { name: "Discord", icon: "discord.svg" },
)
```

#### `.withDefaultConfig(config)`

Sets default config for system connectors. Users cannot override.

| Parameter | Type                        | Description    |
| --------- | --------------------------- | -------------- |
| `config`  | inferred from config schema | Default values |

#### `.onContext(hook)`

Creates shared context injected into every action handler.

| Parameter | Type                                        | Description                   |
| --------- | ------------------------------------------- | ----------------------------- |
| `hook`    | `({ config, scope, identity }) => TContext` | Sync or async context factory |

#### `.onValidate(hook)`

Validates config before connecting. Throw to reject.

| Parameter | Type                                                     | Description         |
| --------- | -------------------------------------------------------- | ------------------- |
| `hook`    | `({ config, scope, identity }) => void \| Promise<void>` | Validation function |

#### `.withOAuth(options)`

Enables OAuth 2.0 authentication.

| Option                  | Type                                          | Required | Description                   |
| ----------------------- | --------------------------------------------- | -------- | ----------------------------- |
| `authorizationUrl`      | `string`                                      | Yes      | Provider's authorize endpoint |
| `tokenUrl`              | `string`                                      | Yes      | Provider's token endpoint     |
| `clientId`              | `string`                                      | Yes      | App client ID                 |
| `clientSecret`          | `string`                                      | Yes      | App client secret             |
| `scopes`                | `string[]`                                    | No       | OAuth scopes                  |
| `pkce`                  | `boolean`                                     | No       | Enable PKCE (S256)            |
| `extraParams`           | `Record<string, string>`                      | No       | Extra auth URL params         |
| `userInfoUrl`           | `string`                                      | No       | User profile endpoint         |
| `parseTokenResponse`    | `(response) => IgniterConnectorOAuthTokens`   | No       | Custom token parser           |
| `parseUserInfoResponse` | `(response) => IgniterConnectorOAuthUserInfo` | No       | Custom user info parser       |

#### `.withWebhook(options)`

Enables incoming webhook handling.

| Option        | Type                                                                  | Required | Description                |
| ------------- | --------------------------------------------------------------------- | -------- | -------------------------- |
| `schema`      | `StandardSchemaV1`                                                    | Yes      | Payload validation schema  |
| `handler`     | `({ payload, config, context, scope, identity, headers }) => TResult` | Yes      | Webhook handler            |
| `description` | `string`                                                              | No       | Human-readable description |
| `verify`      | `(request, config) => boolean \| Promise<boolean>`                    | No       | Signature verification     |

#### `.addAction(key, options)`

Adds an executable action to the connector.

| Option        | Type                                       | Required | Description                |
| ------------- | ------------------------------------------ | -------- | -------------------------- |
| `input`       | `StandardSchemaV1`                         | Yes      | Action input schema        |
| `output`      | `StandardSchemaV1`                         | No       | Action output schema       |
| `description` | `string`                                   | No       | Human-readable description |
| `handler`     | `(context) => TOutput \| Promise<TOutput>` | Yes      | Action implementation      |

#### `.build()`

Finalizes the definition. Returns `IgniterConnectorDefinition`.

***

## IgniterConnectorManager

Static `create()` factory for building the connector manager.

### `IgniterConnectorManager.create()`

Creates a new `IgniterConnectorManagerBuilder`.

```typescript
const builder = IgniterConnectorManager.create();
```

### Builder Methods

#### `.withDatabase(adapter)`

Sets the persistence adapter. **Required.**

| Parameter | Type                      | Description               |
| --------- | ------------------------- | ------------------------- |
| `adapter` | `IgniterConnectorAdapter` | Database adapter instance |

#### `.withLogger(logger)`

Sets a logger for debug visibility.

| Parameter | Type            | Description                                          |
| --------- | --------------- | ---------------------------------------------------- |
| `logger`  | `IgniterLogger` | Object with `debug`, `info`, `warn`, `error` methods |

#### `.withTelemetry(telemetry)`

Enables automatic telemetry event emission.

| Parameter   | Type                      | Description                                    |
| ----------- | ------------------------- | ---------------------------------------------- |
| `telemetry` | `IgniterTelemetryManager` | Telemetry runtime from `@igniter-js/telemetry` |

#### `.withEncrypt(fields, callbacks?)`

Configures field encryption.

| Parameter           | Type                                   | Required | Description             |
| ------------------- | -------------------------------------- | -------- | ----------------------- |
| `fields`            | `string[]`                             | Yes      | Field names to encrypt  |
| `callbacks.encrypt` | `(value) => string \| Promise<string>` | No       | Custom encrypt function |
| `callbacks.decrypt` | `(value) => string \| Promise<string>` | No       | Custom decrypt function |

#### `.addScope(key, options?)`

Registers a scope.

| Parameter          | Type      | Required | Description                                    |
| ------------------ | --------- | -------- | ---------------------------------------------- |
| `key`              | `string`  | Yes      | Unique scope identifier                        |
| `options.required` | `boolean` | No       | Whether identity is required (default: `true`) |

#### `.addConnector(key, definition)`

Registers a connector definition.

| Parameter    | Type                         | Required | Description                 |
| ------------ | ---------------------------- | -------- | --------------------------- |
| `key`        | `string`                     | Yes      | Unique connector identifier |
| `definition` | `IgniterConnectorDefinition` | Yes      | Built connector definition  |

#### `.onConnect(hook)`

Hook called after connection succeeds.

| Parameter | Type                                                                | Description      |
| --------- | ------------------------------------------------------------------- | ---------------- |
| `hook`    | `({ connector, config, scope, identity }) => void \| Promise<void>` | Connect callback |

#### `.onDisconnect(hook)`

Hook called after disconnection.

| Parameter | Type                                                        | Description         |
| --------- | ----------------------------------------------------------- | ------------------- |
| `hook`    | `({ connector, scope, identity }) => void \| Promise<void>` | Disconnect callback |

#### `.onError(hook)`

Hook called when errors occur.

| Parameter | Type                                                                                      | Description    |
| --------- | ----------------------------------------------------------------------------------------- | -------------- |
| `hook`    | `({ error, connector?, operation, scope?, identity?, action? }) => void \| Promise<void>` | Error callback |

#### `.build()`

Finalizes the manager. Returns `IgniterConnectorManagerCore`.

***

## Manager Instance

After `.build()`, the manager provides these operations:

### `connectors.scope(scopeKey, identity?)`

Creates a scoped instance for a specific scope + identity.

| Parameter  | Type     | Required                    | Description          |
| ---------- | -------- | --------------------------- | -------------------- |
| `scopeKey` | `string` | Yes                         | Registered scope key |
| `identity` | `string` | For `required: true` scopes | Scope identifier     |

Returns `IgniterConnectorScoped`.

### `connectors.on(handler)`

Subscribes to events globally.

Returns `IgniterConnectorEventSubscription` with `.unsubscribe()`.

### `connectors.emit(event)`

Emits a custom event to all handlers and telemetry.

### `connectors.handle(operation, request)`

Handles OAuth callbacks and webhooks.

| Operation          | Description                       |
| ------------------ | --------------------------------- |
| `"oauth.callback"` | Process an OAuth callback request |
| `"webhook"`        | Process a webhook request         |

Returns `Response`.

### `connectors.handleOAuthConnect(connectorKey, params)`

Handles OAuth connect flow.

| Parameter            | Type     | Description          |
| -------------------- | -------- | -------------------- |
| `connectorKey`       | `string` | Connector to connect |
| `params.scope`       | `string` | Scope type           |
| `params.identity`    | `string` | Scope identifier     |
| `params.redirectUrl` | `string` | Post-OAuth redirect  |
| `params.redirectUri` | `string` | OAuth callback URI   |

### `connectors.list(options?)`

Lists available connectors with metadata. Non-scoped.

| Option              | Type      | Description              |
| ------------------- | --------- | ------------------------ |
| `where.name`        | `string`  | Filter by metadata name  |
| `count.connections` | `boolean` | Include connection count |

### `connectors.get(connectorKey, options?)`

Gets a connector's metadata. Non-scoped.

### `connectors.getAdapter()`, `getLogger()`, `getTelemetry()`, `getScopes()`, `getConnectors()`, `getConnector(key)`, `getOAuthHandler(key)`, `getEncryption()`, `getHooks()`

Accessors for manager internals.

***

## Scoped Instance

Returned by `connectors.scope()`. Provides per-tenant operations.

### `scoped.connect(connectorKey, config)`

Connects a connector for this scope.

| Parameter      | Type                        | Description                        |
| -------------- | --------------------------- | ---------------------------------- |
| `connectorKey` | `string`                    | Connector to connect               |
| `config`       | inferred from config schema | Configuration (or empty for OAuth) |

For OAuth connectors: returns a redirect `Response`.
For non-OAuth connectors: returns `void`.

### `scoped.disconnect(connectorKey)`

Removes a connection.

### `scoped.toggle(connectorKey, enabled?)`

Toggles or sets enabled state.

| Parameter      | Type      | Required | Description                         |
| -------------- | --------- | -------- | ----------------------------------- |
| `connectorKey` | `string`  | Yes      | Connector to toggle                 |
| `enabled`      | `boolean` | No       | Explicit state (toggles if omitted) |

### `scoped.update(connectorKey, config)`

Updates connector configuration without disconnecting.

### `scoped.list(options?)`

Lists connected connectors for this scope.

| Option              | Type      | Description               |
| ------------------- | --------- | ------------------------- |
| `where.enabled`     | `boolean` | Filter by enabled state   |
| `where.name`        | `string`  | Filter by metadata name   |
| `limit`             | `number`  | Max results               |
| `offset`            | `number`  | Pagination offset         |
| `count.connections` | `boolean` | Include connection counts |

Returns `IgniterConnectorInstance[]`.

### `scoped.get(connectorKey, options?)`

Gets a specific connector instance.

Returns `IgniterConnectorInstance | null`.

### `scoped.count(options?)`

Counts connected connectors.

### `scoped.action(connectorKey, actionKey).call(input)`

Executes a connector action.

Returns `Promise<{ data: TOutput | null; error: Error | null }>`.

### `scoped.on(handler)`

Subscribes to events for this scope only.

Returns `IgniterConnectorEventSubscription`.

***

## Event Types

### IgniterConnectorEvent (Union)

| Discriminated by `type`  | Additional Properties                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
| `connector.connected`    | —                                                                                                       |
| `connector.disconnected` | —                                                                                                       |
| `connector.enabled`      | —                                                                                                       |
| `connector.disabled`     | —                                                                                                       |
| `connector.updated`      | —                                                                                                       |
| `oauth.started`          | —                                                                                                       |
| `oauth.completed`        | `userInfo?: Record<string, unknown>`                                                                    |
| `oauth.refreshed`        | —                                                                                                       |
| `oauth.failed`           | `errorCode: string`, `errorMessage?: string`                                                            |
| `action.started`         | `action: string`                                                                                        |
| `action.completed`       | `action: string`, `durationMs?: number`                                                                 |
| `action.failed`          | `action: string`, `durationMs?: number`, `errorCode: string`, `errorMessage?: string`                   |
| `webhook.received`       | `method?: string`, `path?: string`, `verified?: boolean`                                                |
| `webhook.processed`      | `method?: string`, `path?: string`, `durationMs?: number`                                               |
| `webhook.failed`         | `method?: string`, `path?: string`, `durationMs?: number`, `errorCode: string`, `errorMessage?: string` |
| `error.occurred`         | `error: Error`, `operation?: string`, `errorCode: string`, `errorMessage?: string`                      |

All events include `connector: string`, `scope: string`, `identity: string`, `timestamp: Date`.

***

## Error Codes

```typescript
import { IGNITER_CONNECTOR_ERROR_CODES } from "@igniter-js/connectors";
```

### Connector

* `CONNECTOR_NOT_FOUND` (404)
* `CONNECTOR_NOT_CONNECTED` (400)
* `CONNECTOR_ALREADY_CONNECTED` (409)
* `CONNECTOR_CONFIG_INVALID` (400)
* `CONNECTOR_DEFAULT_CONFIG_REQUIRED` (400)

### Action

* `CONNECTOR_ACTION_NOT_FOUND` (404)
* `CONNECTOR_ACTION_INPUT_INVALID` (400)
* `CONNECTOR_ACTION_OUTPUT_INVALID` (400)
* `CONNECTOR_ACTION_FAILED` (500)

### Scope

* `CONNECTOR_SCOPE_INVALID` (400)
* `CONNECTOR_SCOPE_IDENTIFIER_REQUIRED` (400)

### Database

* `CONNECTOR_DATABASE_REQUIRED` (500)
* `CONNECTOR_DATABASE_FAILED` (500)

### OAuth

* `CONNECTOR_OAUTH_NOT_CONFIGURED` (400)
* `CONNECTOR_OAUTH_STATE_INVALID` (400)
* `CONNECTOR_OAUTH_TOKEN_FAILED` (400)
* `CONNECTOR_OAUTH_PARSE_TOKEN_FAILED` (500)
* `CONNECTOR_OAUTH_PARSE_USERINFO_FAILED` (500)
* `CONNECTOR_OAUTH_REFRESH_FAILED` (400)

### Webhook

* `CONNECTOR_WEBHOOK_NOT_CONFIGURED` (400)
* `CONNECTOR_WEBHOOK_VALIDATION_FAILED` (400)
* `CONNECTOR_WEBHOOK_VERIFICATION_FAILED` (403)

### Encryption

* `CONNECTOR_ENCRYPT_FAILED` (500)
* `CONNECTOR_DECRYPT_FAILED` (500)
* `CONNECTOR_ENCRYPTION_SECRET_REQUIRED` (500)

### Builder

* `CONNECTOR_BUILD_CONFIG_REQUIRED` (500)
* `CONNECTOR_BUILD_SCOPES_REQUIRED` (500)
* `CONNECTOR_BUILD_CONNECTORS_REQUIRED` (500)

***

## Type Helpers

### `$Infer<T>`

Extracts comprehensive type information from a manager instance:

```typescript
import { $Infer } from "@igniter-js/connectors";
type Types = $Infer<typeof connectors>;

type ScopeKey = Types["ScopeKey"];         // "organization" | "user"
type ConnectorKey = Types["ConnectorKey"];  // "telegram" | "discord"
type Config = Types["Config"];              // { telegram: {...}, discord: {...} }
type ActionKey = Types["ActionKey"];        // { telegram: "...", discord: "..." }
type ActionInput = Types["ActionInput"];    // Fully typed action inputs
type ActionOutput = Types["ActionOutput"];  // Fully typed action outputs
type Scoped = Types["Scoped"];             // IgniterConnectorScoped<...>
```

### Other Type Helpers

| Helper                   | Description                              |
| ------------------------ | ---------------------------------------- |
| `$InferScoped<T>`        | Extracts scoped instance type            |
| `$InferConnectorKey<T>`  | Extracts connector key union             |
| `$InferScopeKey<T>`      | Extracts scope key union                 |
| `$InferConfig<T, K>`     | Extracts config for a specific connector |
| `$InferActionKeys<T, K>` | Extracts action keys for a connector     |

***

## Adapter Interface

```typescript
interface IgniterConnectorAdapter {
  get(scope, identity, provider): Promise<IgniterConnectorRecord | null>;
  list(scope, identity): Promise<IgniterConnectorRecord[]>;
  save(scope, identity, provider, value, enabled): Promise<IgniterConnectorRecord>;
  update(scope, identity, provider, data): Promise<IgniterConnectorRecord>;
  delete(scope, identity, provider): Promise<void>;
  exists(scope, identity, provider): Promise<boolean>;
  countConnections(provider): Promise<number>;
  findByWebhookSecret(provider, secret): Promise<IgniterConnectorRecord | null>;
  updateWebhookMetadata(provider, secret, metadata): Promise<void>;
}

interface IgniterConnectorRecord {
  id: string;
  scope: string;
  identity: string;
  provider: string;
  value: Record<string, unknown>;
  enabled: boolean;
  createdAt: Date;
  updatedAt: Date;
}
```

***

## Utilities

### IgniterConnectorCrypto

AES-256-GCM encryption/decryption utilities.

### IgniterConnectorFields

Extract field definitions from Zod schemas for UI rendering.

### IgniterConnectorSchema

Schema validation utilities (StandardSchemaV1).

### IgniterConnectorOAuthUtils

* `generateState()` — CSRF state token
* `generateCodeVerifier()` — PKCE code verifier
* `generateCodeChallenge(verifier)` — PKCE S256 challenge
* `buildAuthUrl(url, params)` — Build authorization URL
* `parseTokenResponse(response)` — Auto-detect token format
* `isExpired(tokens)` — Check token expiration

### IgniterConnectorUrl

* `generateSecret()` — Webhook secret generation
* `buildOAuthCallbackUrl(key)` — OAuth callback URL builder
* `buildWebhookUrl(key, secret)` — Webhook URL builder

***

## Next Steps

* [Getting Started](/docs/connectors/getting-started) — Build your first integration
* [Best Practices](/docs/connectors/best-practices) — Production patterns
* [Troubleshooting](/docs/connectors/troubleshooting) — Error solutions


---

# Best Practices

> Production patterns for connectors — error handling, encryption, scope design, OAuth security, testing, and performance. Do's and don'ts with code examples.
URL: https://igniterjs.com/docs/connectors/best-practices

## Best Practices

This guide covers **production-ready patterns** for building, securing, and scaling connector integrations with `@igniter-js/connectors`.

***

## ✅ Do: Encrypt Sensitive Fields

Always encrypt API keys, tokens, and secrets at rest:

```typescript
// ✅ Good: Encrypt sensitive fields
const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)
  .withEncrypt(["botToken", "apiKey", "accessToken", "refreshToken"])
  .addScope("organization", { required: true })
  .addConnector("telegram", telegram)
  .build();
```

```typescript
// ❌ Bad: No encryption — tokens stored in plain text
const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)
  // No withEncrypt() — all fields stored in plain text!
  .addScope("organization", { required: true })
  .addConnector("telegram", telegram)
  .build();
```

***

## ✅ Do: Handle Errors with Error Codes

Use structured error handling instead of catching everything:

```typescript
// ✅ Good: Switch on error codes
try {
  await scoped.action("telegram", "sendMessage").call({ message: "Hi!" });
} catch (error) {
  if (IgniterConnectorError.isConnectorError(error)) {
    switch (error.code) {
      case "CONNECTOR_NOT_CONNECTED":
        return Response.json(
          { error: "Please connect Telegram first" },
          { status: 400 },
        );
      case "CONNECTOR_ACTION_INPUT_INVALID":
        return Response.json(
          { error: "Invalid input", details: error.message },
          { status: 400 },
        );
    }
  }
  throw error;
}
```

```typescript
// ❌ Bad: Generic catch-all
try {
  await scoped.action("telegram", "sendMessage").call({ message: "Hi!" });
} catch (error) {
  console.error("Something went wrong"); // What went wrong?
  return Response.json({ error: "Internal error" }, { status: 500 });
}
```

***

## ✅ Do: Design Scopes for Your Domain

Model scopes after your authorization model:

```typescript
// ✅ Good: Semantic scopes matching your auth model
const connectors = IgniterConnectorManager.create()
  .addScope("organization", { required: true })  // Per-tenant
  .addScope("user", { required: true })           // Per-user
  .addScope("environment", { required: false })   // Optional env
  .build();
```

```typescript
// ❌ Bad: Vague or meaningless scopes
.addScope("scope1", { required: true })
.addScope("scope2", { required: true })
```

***

## ✅ Do: Use onContext for Shared Dependencies

Avoid creating new SDK instances in every action handler:

```typescript
// ✅ Good: Create SDK once via onContext
const connector = IgniterConnector.create()
  .withConfig(z.object({ apiKey: z.string(), baseUrl: z.string() }))
  .onContext(async ({ config }) => ({
    client: createApiClient(config.baseUrl, config.apiKey),
  }))
  .addAction("getUser", {
    input: z.object({ id: z.string() }),
    handler: async ({ input, context }) => {
      return context.client.get(`/users/${input.id}`);
    },
  })
  .build();
```

```typescript
// ❌ Bad: Creating SDK in every action
.addAction("getUser", {
  input: z.object({ id: z.string() }),
  handler: async ({ input, config }) => {
    const client = createApiClient(config.baseUrl, config.apiKey); // Every call
    return client.get(`/users/${input.id}`);
  },
})
```

***

## ✅ Do: Validate Config Before Saving

Use `onValidate` to check credentials before persisting:

```typescript
// ✅ Good: Validate before saving
.onValidate(async ({ config }) => {
  const response = await fetch("https://api.service.com/health", {
    headers: { Authorization: `Bearer ${config.apiKey}` },
  });
  if (!response.ok) {
    throw new Error("Invalid API key");
  }
})
```

```typescript
// ❌ Bad: Save first, fail later — user left with broken connection
// No onValidate — bad credentials stored, action calls fail mysteriously
```

***

## ✅ Do: Use the Mock Adapter for Tests

Test your connectors without a database:

```typescript
// ✅ Good: Mock adapter for tests
import { IgniterConnectorMockAdapter } from "@igniter-js/connectors/adapters";

beforeEach(() => {
  connectors = IgniterConnectorManager.create()
    .withDatabase(IgniterConnectorMockAdapter.create())
    .addScope("organization", { required: true })
    .addConnector("telegram", telegramConnector)
    .build();
});
```

```typescript
// ❌ Bad: Requiring a real database for tests
// Tests need database setup, seeding, cleanup — slow and fragile
```

***

## ✅ Do: Use Type Inference

Let TypeScript infer types from your connector definitions:

```typescript
// ✅ Good: Type inference from the manager instance
const connectors = IgniterConnectorManager.create()
  .addScope("organization", { required: true })
  .addConnector("telegram", telegramConnector)
  .build();

// Types are inferred:
const scoped = connectors.scope("organization", "org_123");
const { data } = await scoped
  .action("telegram", "sendMessage")
  .call({ message: "Hi!" });
// data: { messageId: string; timestamp: Date } | null
```

```typescript
// ❌ Bad: Manual type annotations
type TelegramConnector = { ... }; // Maintained manually, gets out of sync
const result: { messageId: string } = await callAction(...); // Wrong type?
```

***

## ✅ Do: Enable PKCE for OAuth

Always enable PKCE for better OAuth security:

```typescript
// ✅ Good: PKCE enabled
.withOAuth({
  authorizationUrl: "https://provider.com/oauth/authorize",
  tokenUrl: "https://provider.com/oauth/token",
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  pkce: true,
  scopes: ["read", "write"],
})
```

```typescript
// ❌ Bad: No PKCE — vulnerable to authorization code interception
.withOAuth({
  authorizationUrl: "...",
  tokenUrl: "...",
  clientId: "...",
  clientSecret: "...",
  // pkce: false (default) — less secure
})
```

***

## ✅ Do: Centralize Manager Creation

Create the manager once and export it — don't create new instances per request:

```typescript
// ✅ Good: Singleton manager
// lib/connectors.ts
export const connectors = IgniterConnectorManager.create()
  .withDatabase(IgniterConnectorPrismaAdapter.create(prisma))
  .addScope("organization", { required: true })
  .addConnector("telegram", telegramConnector)
  .build();

// api/routes.ts
import { connectors } from "@/lib/connectors"; // Same instance everywhere
```

```typescript
// ❌ Bad: New manager per request — adapter re-created, memory leak
export function getConnectors() {
  return IgniterConnectorManager.create()
    .withDatabase(IgniterConnectorPrismaAdapter.create(prisma)) // New adapter each call!
    .build();
}
```

***

## ❌ Don't: Store Secrets in Metadata

Metadata is stored in plain text — never put secrets there:

```typescript
// ❌ Bad: Secrets in metadata
.withMetadata(z.object({ apiKey: z.string() }), { apiKey: "sk_live_..." })
```

```typescript
// ✅ Good: Metadata for display only
.withMetadata(
  z.object({ name: z.string(), icon: z.string() }),
  { name: "Mailchimp", icon: "mailchimp.svg" },
)
```

***

## ❌ Don't: Hardcode OAuth Secrets

Always use environment variables for OAuth credentials:

```typescript
// ❌ Bad: Hardcoded secrets
.withOAuth({
  clientId: "abc123",
  clientSecret: "xyz789",
})
```

```typescript
// ✅ Good: Environment variables
.withOAuth({
  clientId: process.env.MAILCHIMP_CLIENT_ID!,
  clientSecret: process.env.MAILCHIMP_CLIENT_SECRET!,
})
```

***

## ❌ Don't: Mix Connector Concerns

Keep connectors focused on one service:

```typescript
// ✅ Good: One connector per service
const telegram = IgniterConnector.create()
  .addAction("sendMessage", { /* ... */ })
  .addAction("sendPhoto", { /* ... */ })
  .build();

const discord = IgniterConnector.create()
  .addAction("sendEvent", { /* ... */ })
  .build();
```

```typescript
// ❌ Bad: Trying to put multiple services in one connector
const messaging = IgniterConnector.create()
  .addAction("telegramSend", { /* ... */ })
  .addAction("discordSend", { /* ... */ })
  .addAction("slackSend", { /* ... */ })
  .build(); // Config schema doesn't fit all services
```

***

## Performance Tips

1. **Singleton manager** — Create once, reuse everywhere
2. **Batch connections** — Connect multiple connectors in parallel
3. **Cache connector instances** — `scoped.get()` results when reading configs frequently
4. **Use mock adapter** — For CI environments to avoid database overhead
5. **Monitor telemetry** — Track `action.completed` durations for slow integrations

```typescript
// ✅ Parallel connections
await Promise.all([
  scoped.connect("telegram", telegramConfig),
  scoped.connect("discord", discordConfig),
  scoped.connect("slack", slackConfig),
]);
```

***

## Next Steps

* [Troubleshooting](/docs/connectors/troubleshooting) — Common errors and solutions
* [API Reference](/docs/connectors/api-reference) — Complete type reference
* [Scopes & Multi-Tenancy](/docs/connectors/scopes) — Advanced scoping patterns


---

# Defining Connectors

> Learn the IgniterConnector.create() builder pattern. Define config schemas, metadata, actions with input/output validation, default configs, and type-safe OAuth hooks.
URL: https://igniterjs.com/docs/connectors/defining-connectors

## Defining Connectors

A **connector definition** is a blueprint for an integration. It describes the configuration users need to provide, the actions they can perform, and optionally OAuth flows or webhook handlers.

Everything starts with `IgniterConnector.create()`, a fluent builder that guides you through defining a complete connector with full type inference.

***

## The Builder Pipeline

```typescript
import { IgniterConnector } from "@igniter-js/connectors";
import { z } from "zod";

const connector = IgniterConnector.create()
  .withConfig(configSchema)          // Required: define the config shape
  .withMetadata(metadataSchema, val) // Optional: static info for UI rendering
  .withDefaultConfig(defaults)       // Optional: system connectors
  .onContext(contextHook)            // Optional: inject dependencies
  .onValidate(validateHook)          // Optional: validate config before connect
  .withOAuth(oauthOptions)           // Optional: OAuth 2.0 flow
  .withWebhook(webhookOptions)       // Optional: incoming webhook handling
  .addAction(key, actionOptions)     // Required: at least one action
  .addAction("anotherAction", ...)   // More actions
  .build();                          // Finalize the definition
```

<Callout type="info">
  The builder is **type-safe at every step**. Each method call narrows the generic types, so `.addAction()` knows your config shape and `.build()` returns the fully inferred definition.
</Callout>

***

## Configuration Schema

The `.withConfig()` method defines what configuration users need to provide when connecting. Use any `StandardSchemaV1`-compatible schema (Zod, Valibot, ArkType).

```typescript
const telegram = IgniterConnector.create()
  .withConfig(
    z.object({
      botToken: z.string().describe("Bot token from @BotFather"),
      chatId: z.string().describe("Target chat ID"),
    }),
  )
  .addAction("ping", {
    input: z.object({}),
    handler: async () => ({ ok: true }),
  })
  .build();
```

### Descriptions

Use `.describe()` on Zod fields to provide helpful hints. These are extracted for UI form rendering:

```typescript
z.object({
  apiKey: z.string().describe("Your API key from the dashboard"),
  webhookSecret: z.string().describe("Secret for verifying webhook signatures"),
  region: z.enum(["us", "eu", "apac"]).describe("API region to connect to"),
})
```

***

## Metadata

Metadata provides **static information** about the connector — useful for rendering connector cards in a UI.

```typescript
const connector = IgniterConnector.create()
  .withConfig(z.object({ apiKey: z.string() }))
  .withMetadata(
    z.object({
      name: z.string(),
      icon: z.string(),
      description: z.string().optional(),
      docsUrl: z.string().url().optional(),
    }),
    {
      name: "Discord",
      icon: "discord.svg",
      description: "Send events to Discord channels via webhooks",
      docsUrl: "https://discord.com/developers",
    },
  )
  .addAction("health", {
    input: z.object({}),
    handler: async () => ({ ok: true }),
  })
  .build();
```

<Callout type="info">
  Metadata is **not encrypted** and is always available even before a connector is connected. Use it for display-only information. Never store secrets in metadata.
</Callout>

***

## Default Configuration

Use `.withDefaultConfig()` for **system connectors** — integrations where the config comes from environment variables, not user input.

```typescript
const openai = IgniterConnector.create()
  .withConfig(
    z.object({
      apiKey: z.string(),
      model: z.string().default("gpt-4o"),
    }),
  )
  .withDefaultConfig({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "gpt-4o-mini",
  })
  .addAction("chat", {
    input: z.object({
      messages: z.array(z.object({
        role: z.enum(["user", "assistant"]),
        content: z.string(),
      })),
    }),
    handler: async ({ input, config }) => {
      const res = await fetch("https://api.openai.com/v1/chat/completions", {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${config.apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ model: config.model, messages: input.messages }),
      });
      return res.json();
    },
  })
  .build();
```

<Callout type="warn">
  Default config **cannot be overridden** by users. Only use for system connectors where all tenants share the same API key. For user-provided credentials, use regular `.withConfig()` without `.withDefaultConfig()`.
</Callout>

***

## Adding Actions

Actions are the operations users can perform on a connector. Each action has:

| Property      | Required | Description                                                  |
| ------------- | -------- | ------------------------------------------------------------ |
| `input`       | **Yes**  | Schema for validating action input                           |
| `output`      | No       | Schema for validating action output (enables type inference) |
| `description` | No       | Human-readable description                                   |
| `handler`     | **Yes**  | Async function that executes the action                      |

```typescript
.addAction("sendMessage", {
  description: "Send a text message to the configured chat",
  input: z.object({
    message: z.string().min(1).max(4096),
    parseMode: z.enum(["HTML", "Markdown"]).optional(),
  }),
  output: z.object({
    messageId: z.string(),
    timestamp: z.date(),
  }),
  handler: async ({ input, config }) => {
    // input.message — fully typed from input schema
    // config.botToken — fully typed from config schema
    return {
      messageId: "123",
      timestamp: new Date(),
    };
  },
})
```

### Handler Context

The handler receives a context object with everything you need:

```typescript
handler: async ({ input, config, context, oauth, scope, identity }) => {
  // input    — validated action input
  // config   — decrypted connector config
  // context  — custom context from onContext hook
  // oauth    — OAuth tokens (if OAuth connector)
  // scope    — scope type (e.g., 'organization')
  // identity — scope identifier (e.g., 'org_123')
}
```

### Action Without Output Schema

If you omit the `output` schema, the return type is inferred from the handler:

```typescript
.addAction("getStatus", {
  input: z.object({}),
  // No output schema — inferred from handler return
  handler: async () => ({
    ok: true as const,
    uptime: process.uptime(),
  }),
})
// `data` will be typed as { ok: true; uptime: number }
```

***

## Context Hook (onContext)

Create reusable dependencies that are injected into every action handler:

```typescript
const connector = IgniterConnector.create()
  .withConfig(z.object({ baseUrl: z.string().url() }))
  .onContext(async ({ config }) => ({
    httpClient: createHttpClient(config.baseUrl),
    cache: createCache(),
  }))
  .addAction("getUser", {
    input: z.object({ id: z.string() }),
    handler: async ({ input, context }) => {
      // context.httpClient — available in every action
      return context.httpClient.get(`/users/${input.id}`);
    },
  })
  .addAction("listUsers", {
    input: z.object({}),
    handler: async ({ context }) => {
      return context.httpClient.get("/users");
    },
  })
  .build();
```

***

## Validation Hook (onValidate)

Validate configuration **before** a connector is connected. Throw an error to reject:

```typescript
const connector = IgniterConnector.create()
  .withConfig(z.object({ apiKey: z.string() }))
  .onValidate(async ({ config }) => {
    const response = await fetch("https://api.service.com/validate", {
      headers: { Authorization: `Bearer ${config.apiKey}` },
    });
    if (!response.ok) {
      throw new Error("Invalid API key — please check your credentials");
    }
  })
  .addAction("data", {
    input: z.object({}),
    handler: async () => ({ ok: true }),
  })
  .build();
```

<Callout type="warn">
  The `onValidate` hook runs **synchronously** during `.connect()`. If it throws, the connection is rejected and no record is saved.
</Callout>

***

## Next Steps

* [Manager Setup](/docs/connectors/manager-setup) — Wire adapters, encryption, and telemetry
* [Actions](/docs/connectors/actions) — Execute actions with error handling
* [OAuth](/docs/connectors/oauth) — Add OAuth authentication


---

# Events

> Subscribe to connector lifecycle, action execution, OAuth flow, and webhook events. Global and scoped subscriptions with typed event objects.
URL: https://igniterjs.com/docs/connectors/events

## Events

Connectors emits structured events for every significant operation — connections, actions, OAuth flows, webhooks, and errors. Subscribe globally or per scope.

***

## Event Types

All events share a base structure:

```typescript
interface IgniterConnectorEventBase {
  connector: string;   // Connector key (e.g., "telegram")
  scope: string;       // Scope type (e.g., "organization")
  identity: string;    // Scope identifier (e.g., "org_123")
  timestamp: Date;     // When the event occurred
}
```

### Connector Lifecycle

| Event Type               | When                           |
| ------------------------ | ------------------------------ |
| `connector.connected`    | After `.connect()` succeeds    |
| `connector.disconnected` | After `.disconnect()` succeeds |
| `connector.enabled`      | After `.toggle(key, true)`     |
| `connector.disabled`     | After `.toggle(key, false)`    |
| `connector.updated`      | After `.update()` succeeds     |

### OAuth

| Event Type        | When                              |
| ----------------- | --------------------------------- |
| `oauth.started`   | OAuth authorization URL generated |
| `oauth.completed` | Token exchange successful         |
| `oauth.refreshed` | Token refresh successful          |
| `oauth.failed`    | Any OAuth step fails              |

### Actions

| Event Type         | When                               |
| ------------------ | ---------------------------------- |
| `action.started`   | Before handler execution           |
| `action.completed` | After handler returns successfully |
| `action.failed`    | After handler throws               |

### Webhooks

| Event Type          | When                      |
| ------------------- | ------------------------- |
| `webhook.received`  | Webhook request received  |
| `webhook.processed` | Webhook handler completed |
| `webhook.failed`    | Webhook handler failed    |

### Errors

| Event Type       | When                           |
| ---------------- | ------------------------------ |
| `error.occurred` | Any connector operation throws |

***

## Global Subscriptions

Subscribe to events across all scopes from the manager:

```typescript
const subscription = connectors.on((event) => {
  switch (event.type) {
    case "connector.connected":
      console.log(`🔌 ${event.connector} connected for ${event.scope}:${event.identity}`);
      break;

    case "connector.disconnected":
      console.log(`🔌 ${event.connector} disconnected from ${event.scope}:${event.identity}`);
      break;

    case "action.completed":
      console.log(
        `✅ ${event.connector}.${event.action} completed in ${event.durationMs}ms`
      );
      break;

    case "action.failed":
      console.error(
        `❌ ${event.connector}.${event.action} failed: ${event.errorMessage}`
      );
      break;

    case "oauth.failed":
      console.error(`🔐 OAuth failed for ${event.connector}: ${event.errorMessage}`);
      break;

    case "error.occurred":
      console.error(`💥 ${event.operation} error in ${event.connector}:`, event.error);
      break;
  }
});

// Unsubscribe when done
subscription.unsubscribe();
```

***

## Scoped Subscriptions

Subscribe to events for a specific scope:

```typescript
const scoped = connectors.scope("organization", "org_123");

const sub = scoped.on((event) => {
  // Only receives events for organization:org_123
  console.log(`[${event.scope}:${event.identity}] ${event.type}`);
});

sub.unsubscribe();
```

***

## Typed Event Handling

All events are fully typed. Use `IgniterConnectorEvent` to pattern-match:

```typescript
import type { IgniterConnectorEvent } from "@igniter-js/connectors";

connectors.on((event: IgniterConnectorEvent) => {
  switch (event.type) {
    case "connector.connected":
      // event is IgniterConnectorConnectedEvent
      break;
    case "action.completed":
      // event is IgniterConnectorActionCompletedEvent
      // event.action is typed as string
      // event.durationMs is typed as number | undefined
      break;
    case "oauth.failed":
      // event is IgniterConnectorOAuthFailedEvent
      // event.errorCode is typed as string
      // event.errorMessage is typed as string | undefined
      break;
    case "webhook.processed":
      // event is IgniterConnectorWebhookProcessedEvent
      // event.method is typed as string | undefined
      // event.durationMs is typed as number | undefined
      break;
  }
});
```

***

## Emitting Custom Events

You can also emit events programmatically:

```typescript
await connectors.emit({
  type: "connector.connected",
  connector: "telegram",
  scope: "organization",
  identity: "org_123",
  timestamp: new Date(),
});
```

***

## Events + Telemetry

When telemetry is enabled, events are **automatically forwarded** to the telemetry system:

```typescript
const telemetry = IgniterTelemetry.create()
  .withService("my-api")
  .addEvents(IgniterConnectorsTelemetryEvents)
  .build();

const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)
  .withTelemetry(telemetry)
  .build();

// Both event handlers AND telemetry receive events
connectors.on((event) => {
  // Custom handling (e.g., Slack notifications)
});

// Telemetry automatically receives:
// igniter.connectors.connector.connected
// igniter.connectors.action.started
// igniter.connectors.action.completed
// ... etc
```

See [Telemetry](/docs/connectors/telemetry) for redaction rules and configuration.

***

## Real-World Example: Metrics Dashboard

Track connector usage with events:

```typescript
const metrics = {
  connections: 0,
  actions: 0,
  errors: 0,
  oauthFlows: 0,
};

connectors.on((event) => {
  switch (event.type) {
    case "connector.connected":
      metrics.connections++;
      break;
    case "action.completed":
    case "action.failed":
      metrics.actions++;
      break;
    case "error.occurred":
      metrics.errors++;
      break;
    case "oauth.started":
      metrics.oauthFlows++;
      break;
  }
});

// Expose metrics
app.get("/metrics", (req, res) => {
  res.json(metrics);
});
```

## Real-World Example: Slack Notifications

```typescript
connectors.on(async (event) => {
  if (event.type === "error.occurred") {
    await fetch(process.env.SLACK_WEBHOOK_URL!, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        text: `🚨 Connector error: ${event.connector} — ${event.operation}`,
        attachments: [{
          color: "danger",
          fields: [
            { title: "Error", value: event.error.message, short: false },
            { title: "Code", value: event.errorCode, short: true },
            { title: "Scope", value: `${event.scope}:${event.identity}`, short: true },
          ],
        }],
      }),
    });
  }
});
```

***

## Next Steps

* [Telemetry](/docs/connectors/telemetry) — Structured observability with redaction
* [Lifecycle Hooks](/docs/connectors/hooks) — Connect and disconnect hooks
* [API Reference](/docs/connectors/api-reference) — Full event type reference


---

# Getting Started

> Build a complete multi-tenant integration from scratch. Define a Telegram connector, set up the manager, and execute actions with full type safety.
URL: https://igniterjs.com/docs/connectors/getting-started

## Getting Started

This guide walks through building a **real multi-tenant Telegram integration** from zero to production-ready — including encryption, scoping, and error handling.

By the end, you'll have a type-safe connector system that can send Telegram messages across multiple organizations.

<Callout type="info">
  We assume you have a Prisma database set up. If you don't have one, the [Mock Adapter](/docs/connectors/adapters#mock-adapter) lets you develop without a database.
</Callout>

***

## Step 1 — Define Your Connector

A connector definition describes the configuration, actions, metadata, and optionally OAuth or webhook setup.

```typescript
// connectors/telegram.ts
import { IgniterConnector } from "@igniter-js/connectors";
import { z } from "zod";

export const telegramConnector = IgniterConnector.create()
  .withConfig(
    z.object({
      botToken: z.string().describe("Your Telegram bot token from @BotFather"),
      chatId: z.string().describe("Target chat ID (user, group, or channel)"),
    }),
  )
  .withMetadata(
    z.object({
      name: z.string(),
      icon: z.string(),
      description: z.string().optional(),
    }),
    {
      name: "Telegram",
      icon: "telegram.svg",
      description: "Send messages to Telegram users, groups, and channels",
    },
  )
  .addAction("sendMessage", {
    description: "Send a text message to the configured chat",
    input: z.object({
      message: z.string().min(1).max(4096),
      parseMode: z.enum(["HTML", "Markdown"]).optional(),
    }),
    output: z.object({
      messageId: z.string(),
      timestamp: z.date(),
    }),
    handler: async ({ input, config }) => {
      const body: Record<string, unknown> = {
        chat_id: config.chatId,
        text: input.message,
      };
      if (input.parseMode) body.parse_mode = input.parseMode;

      const res = await fetch(
        `https://api.telegram.org/bot${config.botToken}/sendMessage`,
        {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(body),
        },
      );

      const data = await res.json() as any;
      if (!data.ok) throw new Error(data.description);

      return {
        messageId: String(data.result.message_id),
        timestamp: new Date(),
      };
    },
  })
  .build();
```

## Step 2 — Set Up the Manager

The manager wires adapters, encryption, scopes, and connectors together.

```typescript
// connectors/manager.ts
import { IgniterConnectorManager } from "@igniter-js/connectors";
import { IgniterConnectorPrismaAdapter } from "@igniter-js/connectors/adapters";
import { PrismaClient } from "@prisma/client";
import { telegramConnector } from "./telegram";

const prisma = new PrismaClient();

export const connectors = IgniterConnectorManager.create()
  .withDatabase(IgniterConnectorPrismaAdapter.create(prisma))
  .withEncrypt(["botToken"]) // botToken encrypted at rest
  .addScope("organization", { required: true })
  .addConnector("telegram", telegramConnector)
  .build();
```

<Callout type="warn">
  **Encryption requires `IGNITER_SECRET`** in your environment variables. Without it, encrypted fields will throw on read/write. Generate one with `openssl rand -hex 32`.
</Callout>

### Prisma Schema

The Prisma adapter expects a model with specific fields. Add this to your Prisma schema:

```prisma
model Connector {
  id        String   @id @default(cuid())
  scope     String
  identity  String
  provider  String
  value     Json
  enabled   Boolean  @default(true)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@unique([scope, identity, provider])
  @@index([provider])
}
```

## Step 3 — Connect a Tenant

Each "tenant" (organization, workspace, user) gets a scoped instance:

```typescript
// api/orgs/[orgId]/telegram/connect.ts
import { connectors } from "@/connectors/manager";

export async function connectTelegram(orgId: string, config: {
  botToken: string;
  chatId: string;
}) {
  const scoped = connectors.scope("organization", orgId);

  await scoped.connect("telegram", config);

  return { success: true };
}
```

## Step 4 — Execute Actions

Once connected, execute typed actions on the scoped instance:

```typescript
// api/orgs/[orgId]/telegram/send.ts
import { connectors } from "@/connectors/manager";

export async function sendTelegramMessage(
  orgId: string,
  message: string,
  parseMode?: "HTML" | "Markdown",
) {
  const scoped = connectors.scope("organization", orgId);

  const { data, error } = await scoped
    .action("telegram", "sendMessage")
    .call({ message, parseMode });

  if (error) {
    console.error("Failed to send message:", error);
    throw error;
  }

  return data; // { messageId: string, timestamp: Date }
}
```

<Callout type="info">
  The return type of `data` is **fully inferred** from your Zod schemas — `{ messageId: string; timestamp: Date }`. No manual type annotations needed.
</Callout>

## Step 5 — Handle Errors

Connectors throws typed errors with stable codes. Catch and handle them:

```typescript
import { IgniterConnectorError } from "@igniter-js/connectors";

try {
  await scoped.action("telegram", "sendMessage").call({ message: "Hi!" });
} catch (error) {
  if (IgniterConnectorError.isConnectorError(error)) {
    switch (error.code) {
      case "CONNECTOR_NOT_CONNECTED":
        // Prompt user to connect first
        return { status: 400, error: "Telegram not connected" };
      case "CONNECTOR_ACTION_INPUT_INVALID":
        // Show validation errors to the user
        return { status: 400, error: error.message };
      default:
        // Log unknown connector errors
        console.error(`[${error.code}]`, error);
    }
  }
  throw error; // Re-throw unexpected errors
}
```

***

## Full Example: Complete API Route

Putting it all together in a **Next.js API route**:

```typescript
// app/api/orgs/[orgId]/notify/route.ts
import { NextRequest, NextResponse } from "next/server";
import { connectors } from "@/connectors/manager";
import { IgniterConnectorError } from "@igniter-js/connectors";

export async function POST(
  req: NextRequest,
  { params }: { params: { orgId: string } },
) {
  try {
    const { message, parseMode } = await req.json();
    const scoped = connectors.scope("organization", params.orgId);

    const { data, error } = await scoped
      .action("telegram", "sendMessage")
      .call({ message, parseMode });

    if (error) throw error;
    return NextResponse.json({ messageId: data.messageId });
  } catch (error) {
    if (IgniterConnectorError.isConnectorError(error)) {
      return NextResponse.json(
        { error: error.message, code: error.code },
        { status: error.statusCode },
      );
    }
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 },
    );
  }
}
```

## Adding a Second Connector

The power of connectors shines when you add more integrations. Here's a Discord connector added to the same manager:

```typescript
// connectors/discord.ts
const discordConnector = IgniterConnector.create()
  .withConfig(
    z.object({
      webhookUrl: z.string().url(),
    }),
  )
  .addAction("sendEvent", {
    input: z.object({
      title: z.string(),
      description: z.string(),
      color: z.number().optional(),
    }),
    handler: async ({ input, config }) => {
      await fetch(config.webhookUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          embeds: [{
            title: input.title,
            description: input.description,
            color: input.color ?? 0x5865F2,
          }],
        }),
      });
    },
  })
  .build();

// Add to manager
const connectors = IgniterConnectorManager.create()
  .withDatabase(IgniterConnectorPrismaAdapter.create(prisma))
  .withEncrypt(["botToken"])
  .addScope("organization", { required: true })
  .addConnector("telegram", telegramConnector)
  .addConnector("discord", discordConnector)
  .build();

// Both work on the same scoped instance
const scoped = connectors.scope("organization", "org_123");
await scoped.action("telegram", "sendMessage").call({ message: "Hi!" });
await scoped.action("discord", "sendEvent").call({
  title: "Deploy Complete",
  description: "Production deployed successfully",
});
```

**✅ Success!** You now have a production-ready multi-tenant integration system with two connectors, encrypted configs, and full type safety.

***

## Next Steps

* [Defining Connectors](/docs/connectors/defining-connectors) — Deep dive into connector definitions
* [Manager Setup](/docs/connectors/manager-setup) — Adapters, encryption, telemetry, and scopes
* [Scopes & Multi-Tenancy](/docs/connectors/scopes) — Advanced scoping patterns
* [OAuth](/docs/connectors/oauth) — Add OAuth authentication to connectors


---

# Lifecycle Hooks

> Hook into connector and manager lifecycle events. Run code on connect, disconnect, errors, config validation, and context injection.
URL: https://igniterjs.com/docs/connectors/hooks

## Lifecycle Hooks

Hooks let you run custom logic at specific points in the connector lifecycle — validation, context injection, connection events, and error handling.

There are two levels of hooks:

| Level               | Scope                    | When to use                                   |
| ------------------- | ------------------------ | --------------------------------------------- |
| **Connector Hooks** | Per connector definition | Validate config, inject shared context        |
| **Manager Hooks**   | Across all connectors    | Audit logging, error reporting, notifications |

***

## Connector Hooks

Defined inside `IgniterConnector.create()`, these hooks run for a specific connector.

### onContext — Inject Dependencies

Create shared context (HTTP clients, SDK instances, caches) available in every action handler:

```typescript
const connector = IgniterConnector.create()
  .withConfig(z.object({ baseUrl: z.string().url() }))
  .onContext(async ({ config, scope, identity }) => ({
    httpClient: createAuthenticatedClient(config.baseUrl, identity),
    cache: new Map(),
  }))
  .addAction("getUser", {
    input: z.object({ id: z.string() }),
    handler: async ({ input, context }) => {
      // context.httpClient — shared across all actions
      return context.httpClient.get(`/users/${input.id}`);
    },
  })
  .addAction("listUsers", {
    input: z.object({}),
    handler: async ({ context }) => {
      // context.cache — also available here
      return context.httpClient.get("/users");
    },
  })
  .build();
```

<Callout type="info">
  `onContext` runs **once per action execution**, not once per connect. It's called before every action, so you get fresh context each time. Use it for clients, not heavy initialization.
</Callout>

### onValidate — Validate Before Connect

Validate configuration before saving a connection. Throw to reject:

```typescript
const connector = IgniterConnector.create()
  .withConfig(z.object({ apiKey: z.string() }))
  .onValidate(async ({ config, scope, identity }) => {
    const response = await fetch("https://api.service.com/ping", {
      headers: { Authorization: `Bearer ${config.apiKey}` },
    });

    if (!response.ok) {
      throw new Error(
        `Invalid API key for scope ${scope}:${identity}. ` +
        `Please check your credentials.`
      );
    }
  })
  .addAction("data", {
    input: z.object({}),
    handler: async () => ({ ok: true }),
  })
  .build();
```

<Callout type="warn">
  If `onValidate` throws, the connection is **rejected entirely** — no record is saved to the database.
</Callout>

***

## Manager Hooks

Defined in `IgniterConnectorManager.create()`, these hooks run for all connectors.

### onConnect — Connection Created

Runs after a connector is successfully connected and saved:

```typescript
const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)
  .addScope("organization", { required: true })
  .addConnector("telegram", telegram)
  .onConnect(async ({ connector, config, scope, identity }) => {
    // Log to audit trail
    await db.auditLog.create({
      data: {
        action: "connector.connected",
        target: connector,
        scope,
        identity,
      },
    });

    // Send notification
    await slack.notify(
      `🔌 ${connector} connected for ${scope}:${identity}`
    );
  })
  .build();
```

### onDisconnect — Connection Removed

Runs after a connector is disconnected (record deleted):

```typescript
.onDisconnect(async ({ connector, scope, identity }) => {
  await db.auditLog.create({
    data: {
      action: "connector.disconnected",
      target: connector,
      scope,
      identity,
    },
  });

  // Clean up related resources
  await cleanupWebhookSubscriptions(connector, scope, identity);
})
```

### onError — Error Occurred

Runs when any connector operation throws:

```typescript
.onError(async ({ error, connector, operation, scope, identity, action }) => {
  // Report to error monitoring
  await Sentry.captureException(error, {
    tags: {
      connector: connector ?? "unknown",
      operation,
      scope: scope ?? "unknown",
    },
    extra: {
      identity,
      action,
    },
  });

  // Log for debugging
  console.error(
    `[Connector Error] ${operation} failed for ${connector}:`,
    error.message,
  );
})
```

### Hook Parameters

| Hook           | Parameters                                                     | When Called                    |
| -------------- | -------------------------------------------------------------- | ------------------------------ |
| `onConnect`    | `{ connector, config, scope, identity }`                       | After `.connect()` succeeds    |
| `onDisconnect` | `{ connector, scope, identity }`                               | After `.disconnect()` succeeds |
| `onError`      | `{ error, connector?, operation, scope?, identity?, action? }` | When any operation throws      |

***

## Real-World Example: Audit Logging

Combine all hooks for a complete audit trail:

```typescript
const connectors = IgniterConnectorManager.create()
  .withDatabase(IgniterConnectorPrismaAdapter.create(prisma))
  .addScope("organization", { required: true })
  .addConnector("telegram", telegramConnector)
  .addConnector("mailchimp", mailchimpConnector)

  // Connection audit
  .onConnect(async (params) => {
    await createAuditEntry("connector.connected", params);
  })

  // Disconnection audit
  .onDisconnect(async (params) => {
    await createAuditEntry("connector.disconnected", params);
  })

  // Error tracking
  .onError(async (params) => {
    await createAuditEntry("connector.error", params, "error");

    if (params.operation === "oauth.callback") {
      await notifyAdmin("OAuth callback failed", params);
    }
  })

  .build();

async function createAuditEntry(
  action: string,
  params: Record<string, unknown>,
  level: "info" | "error" = "info",
) {
  await prisma.auditLog.create({
    data: {
      action,
      level,
      connector: String(params.connector ?? ""),
      scope: String(params.scope ?? ""),
      identity: String(params.identity ?? ""),
      metadata: params,
    },
  });
}
```

***

## Next Steps

* [Events](/docs/connectors/events) — Subscribe to connector lifecycle events
* [Defining Connectors](/docs/connectors/defining-connectors) — Connector hooks in depth
* [Manager Setup](/docs/connectors/manager-setup) — Full manager configuration


---

# Introduction

> Type-safe, multi-tenant connector management for modern TypeScript apps. Build OAuth, API-key, and webhook integrations with encryption, telemetry, and adapter support.
URL: https://igniterjs.com/docs/connectors

## Overview

`@igniter-js/connectors` is a **standalone, builder-based** connector management library for TypeScript applications. It provides a unified, type-safe interface for defining, connecting, and executing actions on third-party integrations — backed by a pluggable adapter architecture.

Whether you need to send Telegram messages, connect to Mailchimp via OAuth, receive Stripe webhooks, or manage hundreds of API integrations across thousands of tenants — connectors gives you the foundation with full TypeScript inference everywhere.

<Callout type="info">
  Connectors is a **fully independent package**. You can use it in any Node.js or Bun application — Express, Next.js, Fastify, Hono, or a background worker. No framework lock-in.
</Callout>

### Key Features

* **Type-safe connectors** — Define config schemas (Zod), action signatures, and get full type inference on scoped instances
* **Multi-tenant scopes** — Isolate integrations per organization, user, workspace, or any custom dimension
* **OAuth 2.0 with PKCE** — Full OAuth lifecycle: authorization, callback, token refresh, and user info fetching
* **AES-256-GCM encryption** — Sensitive fields (API keys, tokens) encrypted at rest with `IGNITER_SECRET`
* **Webhook pipelines** — Define, verify, validate, and handle incoming webhooks with schema validation
* **Adapter system** — Prisma adapter for PostgreSQL/MySQL/SQLite, mock adapter for testing, or build your own
* **Event-driven** — Subscribe to connector lifecycle, action execution, OAuth, and webhook events
* **Telemetry-ready** — Structured observability events with redaction rules for safe production monitoring
* **Predictable errors** — Stable error codes (`CONNECTOR_NOT_FOUND`, `CONNECTOR_ACTION_INPUT_INVALID`) for programmatic handling

***

## Architecture

Connectors follows the **adapter pattern** — the same pattern used across the Igniter.js ecosystem. The manager layer handles scoping, actions, OAuth, events, and encryption. The adapter layer handles persistence.

```mermaid
graph TD
    A[Your App] --> B[scoped.action.call]
    B --> C[IgniterConnectorManagerCore]
    C --> D[Scoped Instance]
    C --> E[OAuth Handler]
    C --> F[Event Emitter]
    C --> G[Encryption]
    D --> H[Adapter Interface]
    H --> I[PrismaAdapter]
    H --> J[MockAdapter]
    H --> K[CustomAdapter]
    I --> L[(Postgres / MySQL / SQLite)]
```

Every operation flows through the same pipeline: **validate → encrypt → persist via adapter → emit events**.

### Mental Model

| Concept                  | What it is                                    | Example                                                            |
| ------------------------ | --------------------------------------------- | ------------------------------------------------------------------ |
| **Connector Definition** | Schema + actions + OAuth + webhook config     | `IgniterConnector.create().withConfig(...).addAction(...).build()` |
| **Manager**              | Wires adapters, encryption, telemetry, scopes | `IgniterConnectorManager.create().withDatabase(...).build()`       |
| **Scoped Instance**      | Per-tenant operations (connect, action, list) | `connectors.scope('organization', 'org_123')`                      |
| **Adapter**              | Database persistence layer                    | `IgniterConnectorPrismaAdapter.create(prisma)`                     |
| **Telemetry**            | Structured observability events               | `IgniterConnectorsTelemetryEvents`                                 |

***

## Quick Start

Get a multi-tenant Telegram connector running in under two minutes.

<Steps>
  <Step>
    ### Install

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        npm install @igniter-js/connectors @igniter-js/common zod
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @igniter-js/connectors @igniter-js/common zod
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @igniter-js/connectors @igniter-js/common zod
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @igniter-js/connectors @igniter-js/common zod
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Define a Connector

    ```typescript
    import { IgniterConnector } from "@igniter-js/connectors";
    import { z } from "zod";

    const telegram = IgniterConnector.create()
      .withConfig(
        z.object({
          botToken: z.string(),
          chatId: z.string(),
        }),
      )
      .addAction("sendMessage", {
        input: z.object({ message: z.string() }),
        output: z.object({ messageId: z.string() }),
        handler: async ({ input, config }) => {
          const res = await fetch(
            `https://api.telegram.org/bot${config.botToken}/sendMessage`,
            {
              method: "POST",
              headers: { "Content-Type": "application/json" },
              body: JSON.stringify({ chat_id: config.chatId, text: input.message }),
            },
          );
          const data = await res.json();
          return { messageId: String(data.result.message_id) };
        },
      })
      .build();
    ```
  </Step>

  <Step>
    ### Create the Manager

    ```typescript
    import { IgniterConnectorManager } from "@igniter-js/connectors";
    import { IgniterConnectorPrismaAdapter } from "@igniter-js/connectors/adapters";

    const connectors = IgniterConnectorManager.create()
      .withDatabase(IgniterConnectorPrismaAdapter.create(prisma))
      .withEncrypt(["botToken"])
      .addScope("organization", { required: true })
      .addConnector("telegram", telegram)
      .build();
    ```
  </Step>

  <Step>
    ### Connect and Execute

    ```typescript
    const scoped = connectors.scope("organization", "org_123");

    await scoped.connect("telegram", {
      botToken: "123456:ABC-DEF1234",
      chatId: "-1001234567890",
    });

    const { data, error } = await scoped
      .action("telegram", "sendMessage")
      .call({ message: "Hello from Igniter.js" });

    if (error) throw error;
    console.log("Message ID:", data?.messageId);
    ```
  </Step>
</Steps>

**✅ Success!** You've created a multi-tenant connector with encrypted config, typed actions, and scoped access.

***

## Next Steps

* [Installation](/docs/connectors/installation) — All package managers and peer dependencies
* [Getting Started](/docs/connectors/getting-started) — Complete walkthrough with a real integration
* [Defining Connectors](/docs/connectors/defining-connectors) — Config schemas, metadata, actions in depth
* [Manager Setup](/docs/connectors/manager-setup) — Adapters, encryption, telemetry, scopes


---

# Installation

> Install and configure @igniter-js/connectors with your preferred package manager. Peers, environment variables, and TypeScript setup.
URL: https://igniterjs.com/docs/connectors/installation

## Installation

### Core Package

Connectors depends on `@igniter-js/common` for shared types and error handling. Both are installed together:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/connectors @igniter-js/common zod
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/connectors @igniter-js/common zod
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/connectors @igniter-js/common zod
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/connectors @igniter-js/common zod
    ```
  </Tab>
</Tabs>

### Adapters Subpath

If using the Prisma adapter, import from the subpath:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/connectors prisma @prisma/client
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/connectors prisma @prisma/client
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/connectors prisma @prisma/client
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/connectors prisma @prisma/client
    ```
  </Tab>
</Tabs>

### Peer Dependencies

| Package              | Required   | Purpose                                                              |
| -------------------- | ---------- | -------------------------------------------------------------------- |
| `@igniter-js/common` | **Yes**    | Shared types (`IgniterLogger`, `StandardSchemaV1`, `IgniterError`)   |
| `zod`                | Optional\* | Schema validation (required if using Zod schemas for config/actions) |

<Callout type="info">
  Connectors supports any `StandardSchemaV1`-compatible validation library. While Zod is the most common choice, you can use Valibot, ArkType, or any schema library that implements Standard Schema v1.
</Callout>

### Environment Variables

| Variable            | Required                      | Description                                                                                       |
| ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `IGNITER_SECRET`    | **Yes** (if using encryption) | AES-256-GCM encryption key. Must be at least 32 characters. Generate with `openssl rand -hex 32`. |
| `IGNITER_BASE_URL`  | Recommended                   | Base URL for OAuth callback and webhook URL generation (e.g., `https://myapp.com`)                |
| `IGNITER_BASE_PATH` | Optional                      | Base path prefix for URL generation (e.g., `/api/v1`)                                             |

```bash
# .env
IGNITER_SECRET=your-64-character-hex-secret-at-least-32-chars
IGNITER_BASE_URL=https://myapp.com
IGNITER_BASE_PATH=/api/v1
```

### TypeScript Configuration

No special TypeScript configuration is required. The package ships with full type declarations. For best results:

```json
// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "module": "ESNext"
  }
}
```

<Callout type="warn">
  Connectors requires **Node.js 22+** and **TypeScript 5.6+**. The package uses `StandardSchemaV1` from the TC39 proposal, which requires TypeScript 5.6+ for full inference.
</Callout>

***

## Next Steps

* [Getting Started](/docs/connectors/getting-started) — Build your first integration in minutes
* [Defining Connectors](/docs/connectors/defining-connectors) — Learn the connector builder API


---

# Manager Setup

> Configure the IgniterConnectorManager with database adapters, encryption, telemetry, scopes, and lifecycle hooks. The central hub for all connector operations.
URL: https://igniterjs.com/docs/connectors/manager-setup

## Manager Setup

The **manager** is the central hub that wires everything together — adapters, encryption, telemetry, scopes, connectors, and lifecycle hooks.

Every connector operation flows through the manager: it validates, encrypts, persists, and emits events.

***

## The Builder Pipeline

```typescript
import { IgniterConnectorManager } from "@igniter-js/connectors";
import { IgniterConnectorPrismaAdapter } from "@igniter-js/connectors/adapters";

const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)            // Required: persistence layer
  .withLogger(logger)               // Optional: debug logging
  .withTelemetry(telemetry)         // Optional: observability
  .withEncrypt(fields, callbacks)   // Recommended: field encryption
  .addScope(key, options)           // Required: at least one scope
  .addConnector(key, definition)    // Required: at least one connector
  .onConnect(hook)                  // Optional: lifecycle hooks
  .onDisconnect(hook)               // Optional
  .onError(hook)                    // Optional
  .build();                         // Finalize the manager
```

***

## Database Adapter

The adapter is the **only required** option. Choose based on your stack:

```typescript
import { IgniterConnectorPrismaAdapter } from "@igniter-js/connectors/adapters";
import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

const connectors = IgniterConnectorManager.create()
  .withDatabase(IgniterConnectorPrismaAdapter.create(prisma))
  // ...
  .build();
```

### Custom Model Name

By default, the Prisma adapter uses a model called `Connector`. Override it:

```typescript
.withDatabase(
  IgniterConnectorPrismaAdapter.create(prisma, { model: "Integration" })
)
```

See [Adapters](/docs/connectors/adapters) for the mock adapter and custom adapters.

***

## Encryption

Encrypt sensitive fields at rest using AES-256-GCM or custom encryption:

```typescript
// Built-in AES-256-GCM (requires IGNITER_SECRET env)
.withEncrypt(["botToken", "apiKey", "accessToken", "refreshToken"])

// Custom encryption
.withEncrypt(["apiKey"], {
  encrypt: async (value) => myEncrypt(value),
  decrypt: async (value) => myDecrypt(value),
})
```

**Fields in the encrypt list** are automatically encrypted before storage and decrypted when read. Other fields remain in plain text.

<Callout type="warn">
  **If you use encryption, `IGNITER_SECRET` must be set.** Without it, the default AES-256-GCM encryption will throw. The secret must be at least 32 characters. Generate one with `openssl rand -hex 32`.
</Callout>

***

## Logger

Pass any object implementing the `IgniterLogger` interface for debug visibility:

```typescript
.withLogger({
  debug: (msg, ...args) => console.debug(`[Connector] ${msg}`, ...args),
  info: (msg, ...args) => console.info(`[Connector] ${msg}`, ...args),
  warn: (msg, ...args) => console.warn(`[Connector] ${msg}`, ...args),
  error: (msg, ...args) => console.error(`[Connector] ${msg}`, ...args),
})
```

***

## Telemetry

Enable structured observability with the telemetry integration:

```typescript
import { IgniterTelemetry } from "@igniter-js/telemetry";
import { IgniterConnectorsTelemetryEvents } from "@igniter-js/connectors/telemetry";

const telemetry = IgniterTelemetry.create()
  .withService("my-api")
  .addEvents(IgniterConnectorsTelemetryEvents)
  .withRedaction({
    denylistKeys: ["config", "accessToken", "refreshToken", "payload"],
    hashKeys: ["ctx.connector.identity"],
  })
  .build();

const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)
  .withTelemetry(telemetry) // Events auto-emitted!
  .addScope("organization", { required: true })
  .addConnector("telegram", telegram)
  .build();
```

See [Telemetry](/docs/connectors/telemetry) for a full guide on events, redaction, and observability.

***

## Scopes

Scopes model **multi-tenancy**. Each scope represents a dimension of isolation:

```typescript
.addScope("organization", { required: true })  // Must always provide identity
.addScope("user", { required: true })           // Per-user connectors
.addScope("system", { required: false })        // Optional system-wide connectors
```

At least one scope is required. See [Scopes & Multi-Tenancy](/docs/connectors/scopes) for deep patterns.

***

## Adding Connectors

Register connector definitions with unique keys:

```typescript
.addConnector("telegram", telegramConnector)
.addConnector("mailchimp", mailchimpConnector)
.addConnector("stripe", stripeConnector)
```

The key becomes the **provider identifier** and is used in all operations:

* `scoped.connect("telegram", config)`
* `scoped.action("telegram", "sendMessage").call(input)`
* `scoped.get("telegram")`

***

## Lifecycle Hooks

Hooks run at specific points in the connector lifecycle:

```typescript
const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)
  .addScope("organization", { required: true })
  .addConnector("telegram", telegram)
  .onConnect(async ({ connector, scope, identity, config }) => {
    await auditLog.create({
      action: "connector.connected",
      connector,
      scope,
      identity,
    });
  })
  .onDisconnect(async ({ connector, scope, identity }) => {
    await auditLog.create({
      action: "connector.disconnected",
      connector,
      scope,
      identity,
    });
  })
  .onError(async ({ error, connector, operation }) => {
    await errorReporter.captureException(error, {
      tags: { connector, operation },
    });
  })
  .build();
```

See [Lifecycle Hooks](/docs/connectors/hooks) for the full hooks API.

***

## Non-Scoped Operations

The manager also provides operations that work **across scopes**:

```typescript
// List all registered connectors with metadata
const available = await connectors.list();
// [{ key: "telegram", type: "custom", metadata: {...} }, ...]

// Get a connector's metadata
const info = await connectors.get("telegram");

// Subscribe to events globally
const sub = connectors.on((event) => {
  console.log(`[${event.type}] ${event.connector}`);
});

// Handle OAuth callbacks and webhooks at the manager level
const response = await connectors.handle("oauth.callback", request);
const response = await connectors.handle("webhook", request);
```

***

## Full Example

```typescript
import { IgniterConnectorManager } from "@igniter-js/connectors";
import { IgniterConnectorPrismaAdapter } from "@igniter-js/connectors/adapters";
import { IgniterTelemetry } from "@igniter-js/telemetry";
import { IgniterConnectorsTelemetryEvents } from "@igniter-js/connectors/telemetry";
import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

const telemetry = IgniterTelemetry.create()
  .withService("integrations-service")
  .addEvents(IgniterConnectorsTelemetryEvents)
  .withRedaction({
    denylistKeys: ["config", "accessToken", "refreshToken", "payload"],
  })
  .build();

export const connectors = IgniterConnectorManager.create()
  .withDatabase(IgniterConnectorPrismaAdapter.create(prisma))
  .withLogger(console)
  .withTelemetry(telemetry)
  .withEncrypt(["botToken", "apiKey", "accessToken", "refreshToken"])
  .addScope("organization", { required: true })
  .addScope("user", { required: true })
  .addConnector("telegram", telegramConnector)
  .addConnector("mailchimp", mailchimpConnector)
  .onConnect(async ({ connector, scope, identity }) => {
    console.log(`[+] ${connector} connected for ${scope}:${identity}`);
  })
  .onError(async ({ error, connector, operation }) => {
    console.error(`[!] ${operation} failed for ${connector}:`, error.message);
  })
  .build();
```

***

## Next Steps

* [Scopes & Multi-Tenancy](/docs/connectors/scopes) — Advanced scoping patterns
* [Actions](/docs/connectors/actions) — Execute connector actions
* [Lifecycle Hooks](/docs/connectors/hooks) — All hook types


---

# OAuth

> Add OAuth 2.0 authentication to your connectors. Full lifecycle: authorization URL generation, PKCE, token exchange, refresh, and user info fetching.
URL: https://igniterjs.com/docs/connectors/oauth

## OAuth

OAuth connectors handle the **full OAuth 2.0 lifecycle** — authorization, callback, token exchange, refresh, and user info fetching. Define it once in your connector definition and the manager handles the rest.

***

## Enabling OAuth

Add `.withOAuth()` to your connector definition:

```typescript
const mailchimp = IgniterConnector.create()
  .withConfig(
    z.object({
      dc: z.string().describe("Data center prefix (e.g., us6)"),
    }),
  )
  .withDefaultConfig({ dc: "us6" })  // Default DC, user provides the rest via OAuth
  .withOAuth({
    authorizationUrl: "https://login.mailchimp.com/oauth2/authorize",
    tokenUrl: "https://login.mailchimp.com/oauth2/token",
    clientId: process.env.MAILCHIMP_CLIENT_ID!,
    clientSecret: process.env.MAILCHIMP_CLIENT_SECRET!,
    scopes: [],
  })
  .addAction("lists", {
    input: z.object({}),
    handler: async ({ config, oauth }) => {
      const res = await fetch(
        `https://${config.dc}.api.mailchimp.com/3.0/lists`,
        {
          headers: { Authorization: `Bearer ${oauth?.accessToken}` },
        },
      );
      return res.json();
    },
  })
  .build();
```

<Callout type="info">
  When OAuth is enabled, **`config` requires `.withDefaultConfig()`**. The system-managed OAuth fields (tokens) are stored separately from user-provided config. Use `.withConfig()` for user fields and `.withDefaultConfig()` for system defaults.
</Callout>

***

## OAuth Options

| Option                  | Required | Description                                         |
| ----------------------- | -------- | --------------------------------------------------- |
| `authorizationUrl`      | **Yes**  | OAuth provider's authorization endpoint             |
| `tokenUrl`              | **Yes**  | OAuth provider's token endpoint                     |
| `clientId`              | **Yes**  | Your app's client ID                                |
| `clientSecret`          | **Yes**  | Your app's client secret                            |
| `scopes`                | No       | Array of OAuth scopes to request                    |
| `pkce`                  | No       | Enable PKCE (S256). Recommended for public clients. |
| `extraParams`           | No       | Extra query params added to authorization URL       |
| `userInfoUrl`           | No       | Endpoint to fetch user profile after OAuth          |
| `parseTokenResponse`    | No       | Custom parser for non-standard token responses      |
| `parseUserInfoResponse` | No       | Custom parser for non-standard user info responses  |

***

## The OAuth Flow

### Step 1 — Generate Authorization URL

Call `.connect()` on an OAuth connector to get the authorization URL:

```typescript
const scoped = connectors.scope("organization", "org_123");

const result = await scoped.connect("mailchimp");

// For OAuth connectors, connect() returns a Response with the auth URL
// You should redirect the user to this URL
return result; // HTTP 302 redirect to authorizationUrl
```

Internally, the manager:

1. Generates a state token for CSRF protection
2. Generates PKCE code verifier + challenge (if enabled)
3. Stores the pending state in memory (10-minute expiration)
4. Returns a redirect response to the authorization URL

### Step 2 — Handle the Callback

After the user authorizes, the provider redirects to your callback URL. Handle it with:

```typescript
// app/api/oauth/callback/route.ts
export async function GET(request: Request) {
  const response = await connectors.handle("oauth.callback", request);
  return response; // Redirects user to success page or back to app
}
```

Or at the scoped level:

```typescript
const scoped = connectors.scope("organization", "org_123");
await scoped.oauth.handleCallback(request);
```

The manager:

1. Validates the state token (CSRF protection)
2. Exchanges the authorization code for tokens
3. Fetches user info (if `userInfoUrl` is configured)
4. Encrypts and saves tokens
5. Emits `oauth.completed` event

### Step 3 — Use OAuth Tokens in Actions

OAuth tokens are automatically injected into action handlers:

```typescript
.addAction("lists", {
  input: z.object({}),
  handler: async ({ oauth }) => {
    // oauth.accessToken  — always available
    // oauth.refreshToken — if provided by the OAuth provider
    // oauth.expiresAt    — if returned
    // oauth.expiresIn    — if returned
    // oauth.userInfo     — from userInfoUrl response

    const res = await fetch("https://api.service.com/data", {
      headers: { Authorization: `Bearer ${oauth?.accessToken}` },
    });
    return res.json();
  },
})
```

***

## PKCE (Proof Key for Code Exchange)

Enable PKCE for enhanced security — recommended for all OAuth flows:

```typescript
.withOAuth({
  authorizationUrl: "https://provider.com/oauth/authorize",
  tokenUrl: "https://provider.com/oauth/token",
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  pkce: true,  // ✅ Enable PKCE (S256)
  scopes: ["read", "write"],
})
```

The manager handles code verifier generation, S256 challenge, and includes the verifier in the token exchange.

***

## Custom Token Parsing

If your OAuth provider returns non-standard token responses, use `parseTokenResponse`:

```typescript
.withOAuth({
  authorizationUrl: "https://custom-provider.com/auth",
  tokenUrl: "https://custom-provider.com/token",
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  parseTokenResponse: (response) => ({
    accessToken: String(response.data.token),
    refreshToken: String(response.data.refresh),
    expiresIn: Number(response.data.expires_in_seconds),
  }),
})
```

The default parser auto-detects common formats (`access_token`, `accessToken`, `token`), but custom parsing gives you full control.

***

## Custom User Info Parsing

```typescript
.withOAuth({
  // ...
  userInfoUrl: "https://custom-provider.com/api/me",
  parseUserInfoResponse: (response) => ({
    id: String(response.account.id),
    email: String(response.account.email),
    name: String(response.account.display_name),
    avatar: String(response.account.avatar_url),
  }),
})
```

***

## Token Refresh

The manager handles token refresh automatically when possible. You can also trigger it manually:

```typescript
const scoped = connectors.scope("organization", "org_123");

// Refresh tokens for a connector
await scoped.oauth.refreshToken("mailchimp");
```

<Callout type="warn">
  Token refresh requires the connector to have a valid `refreshToken`. Not all OAuth providers return refresh tokens. Check your provider's documentation.
</Callout>

***

## OAuth Events

| Event             | When                        |
| ----------------- | --------------------------- |
| `oauth.started`   | Authorization URL generated |
| `oauth.completed` | Successful token exchange   |
| `oauth.refreshed` | Token refresh successful    |
| `oauth.failed`    | Any OAuth step fails        |

```typescript
connectors.on((event) => {
  if (event.type === "oauth.completed") {
    console.log(`✅ OAuth complete for ${event.connector}`);
  }
  if (event.type === "oauth.failed") {
    console.error(
      `❌ OAuth failed for ${event.connector}: ${event.errorMessage}`
    );
  }
});
```

***

## Real-World Example: Full OAuth Endpoints (Next.js)

```typescript
// app/api/integrations/[provider]/connect/route.ts
export async function POST(
  req: NextRequest,
  { params }: { params: { provider: string } },
) {
  const scoped = connectors.scope("organization", getOrgId(req));
  const response = await scoped.connect(params.provider);
  return response;
}

// app/api/integrations/[provider]/callback/route.ts
export async function GET(
  req: NextRequest,
  { params }: { params: { provider: string } },
) {
  const response = await connectors.handle("oauth.callback", req as any);
  return response;
}
```

***

## Next Steps

* [Webhooks](/docs/connectors/webhooks) — Incoming webhook handling
* [Events](/docs/connectors/events) — Full event system reference
* [Troubleshooting](/docs/connectors/troubleshooting) — Common OAuth errors and solutions


---

# Scopes & Multi-Tenancy

> Isolate integrations per organization, user, or environment with typed scopes. Learn required vs optional scopes, nesting, and cross-scope operations.
URL: https://igniterjs.com/docs/connectors/scopes

## Scopes & Multi-Tenancy

Scopes are the **multi-tenancy model** in connectors. They let you isolate integrations by organization, user, workspace, environment, or any custom dimension — each with its own connections, configs, and state.

***

## How Scopes Work

A scope is a **dimension of isolation**. When you create a scoped instance, all operations (connect, disconnect, actions, events) are bound to that scope:

```typescript
// Define scopes at manager level
const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)
  .addScope("organization", { required: true })
  .addScope("user", { required: true })
  .addConnector("telegram", telegram)
  .build();

// Create scoped instances
const orgScoped = connectors.scope("organization", "org_123");
const userScoped = connectors.scope("user", "user_456");

// Each has independent connections
await orgScoped.connect("telegram", { botToken: "...", chatId: "..." });
await userScoped.connect("telegram", { botToken: "...", chatId: "..." });
```

***

## Required vs Optional Scopes

### Required Scopes

When a scope is **required**, you must provide an identity:

```typescript
.addScope("organization", { required: true })

// Must provide identity
const scoped = connectors.scope("organization", "org_123"); // ✅

// Throws IgniterConnectorError: CONNECTOR_SCOPE_IDENTIFIER_REQUIRED
const scoped = connectors.scope("organization"); // ❌
```

### Optional Scopes

Optional scopes can be used without an identity — useful for system-wide connectors:

```typescript
.addScope("system", { required: false })

// With identity
const scoped = connectors.scope("system", "production");

// Without identity
const scoped = connectors.scope("system"); // ✅ identity = ""
```

***

## Scoped Operations

A scoped instance provides the full connector API:

### Connect & Disconnect

```typescript
const scoped = connectors.scope("organization", "org_123");

// Connect with config
await scoped.connect("telegram", {
  botToken: "123:abc",
  chatId: "-100123",
});

// Disconnect
await scoped.disconnect("telegram");

// Toggle enabled state
await scoped.toggle("telegram");       // toggle current state
await scoped.toggle("telegram", true); // explicitly enable
await scoped.toggle("telegram", false);// explicitly disable
```

### List & Get

```typescript
// List all connected connectors for this scope
const instances = await scoped.list();
// [{ key: "telegram", type: "custom", enabled: true, config: {...}, ... }]

// Filter by enabled state
const enabled = await scoped.list({ where: { enabled: true } });

// Get a specific connector
const telegram = await scoped.get("telegram");
if (telegram) {
  console.log("Connected:", telegram.enabled);
  console.log("Last updated:", telegram.updatedAt);
}

// Count connections
const count = await scoped.count();
const enabledCount = await scoped.count({ where: { enabled: true } });
```

### Execute Actions

```typescript
const { data, error } = await scoped
  .action("telegram", "sendMessage")
  .call({ message: "Hello!" });

if (error) throw error;
console.log(data.messageId);
```

### Update Config

```typescript
await scoped.update("telegram", { chatId: "-100456" });
```

### Event Subscriptions

```typescript
// Listen to events for this scope only
const sub = scoped.on((event) => {
  console.log(`[${event.type}] ${event.connector}`);
});

// Unsubscribe when done
sub.unsubscribe();
```

***

## Scope Combinations

You can define multiple scopes for **compound isolation**:

```typescript
const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)
  .addScope("organization", { required: true })
  .addScope("user", { required: true })
  .addScope("environment", { required: false })
  .addConnector("telegram", telegram)
  .build();

// Each scope creates independent instances
const orgA = connectors.scope("organization", "org_123");
const orgB = connectors.scope("organization", "org_456");
const user1 = connectors.scope("user", "user_789");
const prodEnv = connectors.scope("environment", "production");
```

<Callout type="warn">
  Each scope+identity pair gets its **own database records**. A Telegram connection for `organization:org_123` is completely independent from `organization:org_456`. They don't share configs, tokens, or state.
</Callout>

***

## Type Inference with Scopes

The manager infers all scope keys from your definitions:

```typescript
const connectors = IgniterConnectorManager.create()
  .addScope("organization", { required: true })
  .addScope("user", { required: true })
  .addConnector("telegram", telegram)
  .addConnector("discord", discord)
  .build();

// $Infer extracts all types
import { $Infer } from "@igniter-js/connectors";
type Types = $Infer<typeof connectors>;

type ScopeKey = Types["ScopeKey"]; // "organization" | "user"
type Scoped = Types["Scoped"];     // IgniterConnectorScoped<...>

// Typed function parameters
async function notifyOrg(
  scoped: Types["Scoped"],
  orgId: string,
  message: string,
) {
  await scoped.action("telegram", "sendMessage").call({ message });
}
```

***

## Real-World Example: SaaS Multi-Tenant

A SaaS platform with organizations, each having multiple users and Slack integrations:

```typescript
const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)
  .addScope("organization", { required: true })
  .addScope("user", { required: false })
  .addConnector("slack", slackConnector)
  .addConnector("github", githubConnector)
  .build();

// Organization-wide Slack integration
const orgSlack = connectors.scope("organization", "org_acme");
await orgSlack.connect("slack", { webhookUrl: "https://hooks.slack.com/..." });

// Per-user GitHub integration
const userGithub = connectors.scope("user", "user_42");
await userGithub.connect("github", { accessToken: "ghp_..." });

// Execute actions
await orgSlack.action("slack", "postMessage").call({
  channel: "#general",
  text: "New deployment complete!",
});

const { data: repos } = await userGithub
  .action("github", "listRepos")
  .call({});
```

***

## Next Steps

* [Actions](/docs/connectors/actions) — Execute typed connector actions
* [Manager Setup](/docs/connectors/manager-setup) — Full manager configuration
* [Lifecycle Hooks](/docs/connectors/hooks) — Hook into connector lifecycle


---

# Telemetry

> Structured observability for connectors. Auto-emitted events with redaction rules for safe production monitoring of connections, actions, OAuth, and webhooks.
URL: https://igniterjs.com/docs/connectors/telemetry

## Telemetry

When telemetry is enabled, connectors **automatically emit structured events** for every operation — connections, actions, OAuth flows, webhooks, and errors. The events follow a consistent schema with safe defaults for production observability.

***

## Enabling Telemetry

Wire the telemetry runtime into the manager:

```typescript
import { IgniterTelemetry } from "@igniter-js/telemetry";
import { IgniterConnectorsTelemetryEvents } from "@igniter-js/connectors/telemetry";
import { IgniterConnectorManager } from "@igniter-js/connectors";

const telemetry = IgniterTelemetry.create()
  .withService("my-api")
  .withEnvironment("production")
  .addEvents(IgniterConnectorsTelemetryEvents)
  .withRedaction({
    denylistKeys: [
      "config",
      "accessToken",
      "refreshToken",
      "clientSecret",
      "apiKey",
      "token",
      "secret",
      "password",
      "payload",
      "input",
      "output",
      "userInfo",
    ],
    hashKeys: ["ctx.connector.identity"],
  })
  .build();

const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)
  .withTelemetry(telemetry) // Events emitted automatically!
  .addScope("organization", { required: true })
  .addConnector("telegram", telegram)
  .build();
```

***

## Auto-Emitted Events

Once telemetry is configured, events are emitted automatically — no manual instrumentation needed.

### Connector Lifecycle

| Event Name                                  | Emitted When                   |
| ------------------------------------------- | ------------------------------ |
| `igniter.connectors.connector.connected`    | `.connect()` succeeds          |
| `igniter.connectors.connector.disconnected` | `.disconnect()` succeeds       |
| `igniter.connectors.connector.enabled`      | `.toggle(key, true)` succeeds  |
| `igniter.connectors.connector.disabled`     | `.toggle(key, false)` succeeds |
| `igniter.connectors.connector.updated`      | `.update()` succeeds           |

### OAuth Flows

| Event Name                           | Emitted When                |
| ------------------------------------ | --------------------------- |
| `igniter.connectors.oauth.started`   | Authorization URL generated |
| `igniter.connectors.oauth.completed` | Token exchange successful   |
| `igniter.connectors.oauth.refreshed` | Token refresh successful    |
| `igniter.connectors.oauth.failed`    | Any OAuth step fails        |

### Actions

| Event Name                            | Emitted When                 |
| ------------------------------------- | ---------------------------- |
| `igniter.connectors.action.started`   | Before handler execution     |
| `igniter.connectors.action.completed` | Handler returns successfully |
| `igniter.connectors.action.failed`    | Handler throws               |

### Webhooks

| Event Name                             | Emitted When                  |
| -------------------------------------- | ----------------------------- |
| `igniter.connectors.webhook.received`  | Request received              |
| `igniter.connectors.webhook.processed` | Handler completed             |
| `igniter.connectors.webhook.failed`    | Verification or handler fails |

### Errors

| Event Name                          | Emitted When         |
| ----------------------------------- | -------------------- |
| `igniter.connectors.error.occurred` | Any operation throws |

### Adapter Operations

| Event Name                          | Emitted When              |
| ----------------------------------- | ------------------------- |
| `igniter.connectors.adapter.get`    | Adapter `get()` called    |
| `igniter.connectors.adapter.list`   | Adapter `list()` called   |
| `igniter.connectors.adapter.upsert` | Adapter `save()` called   |
| `igniter.connectors.adapter.update` | Adapter `update()` called |
| `igniter.connectors.adapter.delete` | Adapter `delete()` called |

***

## Safe Attributes

These attributes are **safe to expose** in telemetry:

| Attribute                       | Description                                |
| ------------------------------- | ------------------------------------------ |
| `ctx.connector.provider`        | Connector key (e.g., `"telegram"`)         |
| `ctx.connector.scope`           | Scope type (e.g., `"organization"`)        |
| `ctx.connector.identity`        | Scope identifier — **hash this**           |
| `ctx.connector.encrypted`       | Whether encryption is enabled              |
| `ctx.connector.encryptedFields` | Number of encrypted fields                 |
| `ctx.action.name`               | Action key being executed                  |
| `ctx.action.durationMs`         | Execution duration                         |
| `ctx.action.success`            | Success/failure flag                       |
| `ctx.oauth.authorizationUrl`    | OAuth provider domain                      |
| `ctx.oauth.pkce`                | Whether PKCE is enabled                    |
| `ctx.webhook.method`            | HTTP method                                |
| `ctx.webhook.verified`          | Whether signature was verified             |
| `ctx.error.code`                | Error code (e.g., `"CONNECTOR_NOT_FOUND"`) |
| `ctx.error.operation`           | Which operation failed                     |

***

## Redaction Rules

**Always redact** these fields — they may contain secrets, PII, or sensitive payloads:

```
config          — Connector configurations (API keys, tokens)
accessToken     — OAuth access tokens
refreshToken    — OAuth refresh tokens
clientSecret    — OAuth client secrets
apiKey          — API keys
token           — Generic tokens
secret          — Webhook secrets, encryption keys
password        — User passwords
payload         — Webhook payloads (may contain PII)
input           — Action inputs (may contain PII)
output          — Action outputs (may contain PII)
userInfo        — User information from OAuth providers
```

```typescript
.withRedaction({
  denylistKeys: [
    "config", "accessToken", "refreshToken", "clientSecret",
    "apiKey", "token", "secret", "password",
    "payload", "input", "output", "userInfo",
  ],
  hashKeys: ["ctx.connector.identity"], // Hash for privacy
})
```

***

## Telemetry Events Schema

The `IgniterConnectorsTelemetryEvents` schema exports the full event definitions using the `IgniterTelemetryEvents` builder:

```typescript
import { IgniterConnectorsTelemetryEvents } from "@igniter-js/connectors/telemetry";

// Namespace: igniter.connectors
// Groups:
//   connector.*  — Lifecycle events
//   oauth.*      — OAuth flow events
//   action.*     — Action execution events
//   webhook.*    — Webhook handling events
//   error.*      — Error events
//   adapter.*    — Adapter operation events
```

***

## Redaction in Practice

### What Gets Redacted

```typescript
const scoped = connectors.scope("organization", "org_123");

await scoped.connect("telegram", {
  botToken: "abc123def456",    // Redacted: config
  chatId: "-1001234567890",    // Redacted: config
});

await scoped.action("telegram", "sendMessage").call({
  message: "Hello customer!",  // Redacted: input
});
```

Telemetry events will contain:

* ✅ `ctx.connector.provider`: `"telegram"`
* ✅ `ctx.connector.scope`: `"organization"`
* ✅ `ctx.connector.identity`: `"sha256:abc123..."` (hashed)
* ✅ `ctx.action.name`: `"sendMessage"`
* ✅ `ctx.action.durationMs`: `245`
* ❌ `config` — redacted
* ❌ `input` — redacted
* ❌ `output` — redacted

***

## Without Telemetry

If you don't configure telemetry, events are **still available** via the event system:

```typescript
connectors.on((event) => {
  // Same events, but only in-memory — no persistence or export
  console.log(`[${event.type}] ${event.connector}`);
});
```

This is lighter weight and suitable for development, logging, or custom monitoring without the telemetry infrastructure.

***

## Next Steps

* [Events](/docs/connectors/events) — All event types and subscriptions
* [Manager Setup](/docs/connectors/manager-setup) — Full telemetry configuration
* [Best Practices](/docs/connectors/best-practices) — Production security patterns


---

# Troubleshooting

> Common errors, their causes, and solutions when working with @igniter-js/connectors. Error codes, encryption issues, OAuth failures, and adapter problems.
URL: https://igniterjs.com/docs/connectors/troubleshooting

## Troubleshooting

This guide covers **common errors and solutions** when working with `@igniter-js/connectors`.

***

## Error Reference

All connector errors extend `IgniterConnectorError` and include a stable `code` property. Catch them with:

```typescript
import { IgniterConnectorError } from "@igniter-js/connectors";

try {
  // connector operations
} catch (error) {
  if (IgniterConnectorError.isConnectorError(error)) {
    console.log(`[${error.code}] ${error.message}`);
  }
}
```

### Connector Errors

| Error Code                    | Cause                                   | Fix                                                                 |
| ----------------------------- | --------------------------------------- | ------------------------------------------------------------------- |
| `CONNECTOR_NOT_FOUND`         | Connector key not registered in manager | Check `addConnector()` calls match the key used in `scope.action()` |
| `CONNECTOR_NOT_CONNECTED`     | No connection exists for this scope     | Call `scoped.connect()` before `scoped.action()`                    |
| `CONNECTOR_ALREADY_CONNECTED` | Connection already exists               | Disconnect first or use `scoped.update()` to change config          |
| `CONNECTOR_DISABLED`          | Connector is toggled off                | Call `scoped.toggle("key", true)` to re-enable                      |
| `CONNECTOR_CONFIG_INVALID`    | Config validation failed                | Check your Zod schema matches the config shape                      |

### Action Errors

| Error Code                        | Cause                                 | Fix                                                    |
| --------------------------------- | ------------------------------------- | ------------------------------------------------------ |
| `CONNECTOR_ACTION_NOT_FOUND`      | Action key doesn't exist on connector | Verify action key spelling matches `addAction()` calls |
| `CONNECTOR_ACTION_INPUT_INVALID`  | Input validation failed               | Check input shape against the action's Zod schema      |
| `CONNECTOR_ACTION_OUTPUT_INVALID` | Handler returned invalid output       | Fix handler to return shape matching output schema     |

### Scope Errors

| Error Code                            | Cause                           | Fix                                                    |
| ------------------------------------- | ------------------------------- | ------------------------------------------------------ |
| `CONNECTOR_SCOPE_INVALID`             | Scope key not registered        | Add scope with `addScope()` before using it            |
| `CONNECTOR_SCOPE_IDENTIFIER_REQUIRED` | Required scope missing identity | Pass identity to `connectors.scope("key", "identity")` |

### OAuth Errors

| Error Code                           | Cause                          | Fix                                                                    |
| ------------------------------------ | ------------------------------ | ---------------------------------------------------------------------- |
| `CONNECTOR_OAUTH_NOT_CONFIGURED`     | OAuth used but not configured  | Add `.withOAuth()` to connector definition                             |
| `CONNECTOR_OAUTH_STATE_INVALID`      | State token expired or missing | Redirect user to authorization URL again (state expires in 10 minutes) |
| `CONNECTOR_OAUTH_TOKEN_FAILED`       | Token exchange failed          | Check clientId/clientSecret, verify provider response                  |
| `CONNECTOR_OAUTH_PARSE_TOKEN_FAILED` | Cannot parse token response    | Use `parseTokenResponse` option for non-standard providers             |
| `CONNECTOR_OAUTH_REFRESH_FAILED`     | Token refresh failed           | Token may be revoked; prompt user to reconnect                         |

### Webhook Errors

| Error Code                              | Cause                           | Fix                                          |
| --------------------------------------- | ------------------------------- | -------------------------------------------- |
| `CONNECTOR_WEBHOOK_NOT_CONFIGURED`      | Webhook used but not configured | Add `.withWebhook()` to connector definition |
| `CONNECTOR_WEBHOOK_VALIDATION_FAILED`   | Payload doesn't match schema    | Check webhook payload shape against schema   |
| `CONNECTOR_WEBHOOK_VERIFICATION_FAILED` | Signature verification failed   | Check `verify` function and webhook secret   |

### Encryption Errors

| Error Code                             | Cause                           | Fix                                          |
| -------------------------------------- | ------------------------------- | -------------------------------------------- |
| `CONNECTOR_ENCRYPT_FAILED`             | Encryption failed               | Check `IGNITER_SECRET` is set (min 32 chars) |
| `CONNECTOR_DECRYPT_FAILED`             | Decryption failed               | Same secret must be used for encrypt/decrypt |
| `CONNECTOR_ENCRYPTION_SECRET_REQUIRED` | No encryption secret configured | Set `IGNITER_SECRET` environment variable    |

### Builder Errors

| Error Code                            | Cause                       | Fix                                   |
| ------------------------------------- | --------------------------- | ------------------------------------- |
| `CONNECTOR_BUILD_CONFIG_REQUIRED`     | Missing config on connector | Add `.withConfig()` before `.build()` |
| `CONNECTOR_BUILD_SCOPES_REQUIRED`     | No scopes defined           | Add at least one `.addScope()`        |
| `CONNECTOR_BUILD_CONNECTORS_REQUIRED` | No connectors registered    | Add at least one `.addConnector()`    |

***

## Common Issues

### "Encryption: Secret not configured"

**Symptom:** `CONNECTOR_ENCRYPTION_SECRET_REQUIRED` error when connecting or reading connectors.

**Cause:** `IGNITER_SECRET` environment variable is not set.

**Fix:**

```bash
# Generate a secret
openssl rand -hex 32

# Set in your environment
export IGNITER_SECRET="your-64-character-hex-secret"

# Or in .env
IGNITER_SECRET=your-64-character-hex-secret
```

<Callout type="warn">
  **Never commit `IGNITER_SECRET` to your repository.** Use environment variables or a secrets manager. If the secret changes, existing encrypted data becomes unreadable.
</Callout>

***

### "Connector not connected even after connect()"

**Symptom:** Connection appears to succeed but `scoped.get()` returns `null` or `scoped.list()` doesn't include the connector.

**Cause:** Scope mismatch — calling `connect()` on a different scope than where you're reading.

**Fix:**

```typescript
// ❌ Wrong: Different scopes
const orgA = connectors.scope("organization", "org-a");
const orgB = connectors.scope("organization", "org-b");

await orgA.connect("telegram", config);
const instances = await orgB.list(); // Empty! orgB doesn't have the connection

// ✅ Right: Same scope
const orgA = connectors.scope("organization", "org-a");
await orgA.connect("telegram", config);
const instances = await orgA.list(); // Includes telegram
```

***

### "OAuth state invalid or expired"

**Symptom:** `CONNECTOR_OAUTH_STATE_INVALID` error during OAuth callback.

**Cause:** The state token expired (10-minute TTL) or was consumed already.

**Fix:**

1. **State expired** — Redirect user to re-authorize. The authorization flow must complete within 10 minutes.
2. **State consumed twice** — Don't call the callback endpoint multiple times with the same state. Each state token is single-use.
3. **CSRF attack** — If this happens unexpectedly, check for CSRF attempts. The state token prevents authorization code injection.

***

### "Prisma adapter: cannot find model"

**Symptom:** Runtime error about missing model when using the Prisma adapter.

**Cause:** Prisma model name doesn't match or schema not migrated.

**Fix:**

1. Verify the Prisma schema has the `Connector` model (or your custom name)
2. Run `prisma generate`
3. Run `prisma db push` or `prisma migrate dev`
4. If using a custom model name, pass it to the adapter:

```typescript
IgniterConnectorPrismaAdapter.create(prisma, { model: "Integration" })
```

***

### "Action handler hangs or times out"

**Symptom:** Action calls never resolve.

**Cause:** Handler Promise not resolving or infinite loop.

**Fix:**

1. Ensure handler returns a value (or void):

```typescript
// ❌ Bad: Never resolves
handler: async () => {
  await someAsyncOperation();
  // Missing return!
}

// ✅ Good: Returns a value
handler: async () => {
  const result = await someAsyncOperation();
  return result;
}
```

2. Add timeout logic for external API calls:

```typescript
handler: async ({ input, config }) => {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 10000);

  try {
    const response = await fetch(url, { signal: controller.signal });
    return response.json();
  } finally {
    clearTimeout(timeout);
  }
}
```

***

### "Types don't infer correctly"

**Symptom:** TypeScript shows `any` or `unknown` for action inputs/outputs.

**Cause:** Schema library or TypeScript version issue.

**Fix:**

1. Use **Zod 3+** — the most tested schema library
2. Enable strict mode in `tsconfig.json`
3. Ensure `moduleResolution` is set to `bundler` or `node16`
4. Use TypeScript 5.6+ for `StandardSchemaV1` support

```json
// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "module": "ESNext"
  }
}
```

***

## Debugging Tips

### Enable Logger

Add a logger to see internal operations:

```typescript
const connectors = IgniterConnectorManager.create()
  .withDatabase(adapter)
  .withLogger({
    debug: (msg, ...args) => console.debug(`[CONNECTOR:debug] ${msg}`, ...args),
    info: (msg, ...args) => console.info(`[CONNECTOR:info] ${msg}`, ...args),
    warn: (msg, ...args) => console.warn(`[CONNECTOR:warn] ${msg}`, ...args),
    error: (msg, ...args) => console.error(`[CONNECTOR:error] ${msg}`, ...args),
  })
  .build();
```

### Subscribe to Events

Monitor all connector activity:

```typescript
connectors.on((event) => {
  if (event.type === "error.occurred") {
    console.error("Error event:", event);
  }
});
```

### Inspect Adapter Records

Check what's actually stored:

```typescript
const adapter = connectors.getAdapter();
const records = await adapter.list("organization", "org_123");
console.log("Stored records:", records);
```

***

## Next Steps

* [API Reference](/docs/connectors/api-reference) — Full type and method reference
* [Best Practices](/docs/connectors/best-practices) — Production patterns
* [Events](/docs/connectors/events) — Event system debugging


---

# Webhooks

> Handle incoming webhooks with schema validation, signature verification, and typed payloads. Define webhook pipelines inside connector definitions.
URL: https://igniterjs.com/docs/connectors/webhooks

## Webhooks

Connectors can receive and process **incoming webhooks** from external services. Define payload schemas, verification logic, and handler functions right inside your connector definitions — with full type safety.

***

## Defining a Webhook

Add `.withWebhook()` to your connector definition:

```typescript
const stripe = IgniterConnector.create()
  .withConfig(
    z.object({
      webhookSecret: z.string().describe("Stripe webhook signing secret"),
    }),
  )
  .withWebhook({
    description: "Receive Stripe events (payment, subscription, etc.)",
    schema: z.object({
      type: z.string(),
      data: z.object({
        object: z.object({
          id: z.string(),
        }),
      }),
    }),
    handler: async ({ payload, config, scope, identity }) => {
      console.log(`[${scope}:${identity}] Webhook: ${payload.type}`);

      switch (payload.type) {
        case "payment_intent.succeeded":
          await handleSuccessfulPayment(payload.data.object.id, identity);
          break;
        case "customer.subscription.deleted":
          await handleSubscriptionCancelled(payload.data.object.id, identity);
          break;
      }
    },
    verify: async (request, config) => {
      // Verify Stripe signature
      const sig = request.headers["stripe-signature"] as string;
      // Use stripe library to verify
      return verifyStripeWebhook(request.rawBody, sig, config.webhookSecret);
    },
  })
  .addAction("createPayment", {
    input: z.object({
      amount: z.number(),
      currency: z.string(),
    }),
    handler: async ({ input, config }) => {
      // Create payment via Stripe API
    },
  })
  .build();
```

***

## Webhook Options

| Option        | Required | Description                                             |
| ------------- | -------- | ------------------------------------------------------- |
| `schema`      | **Yes**  | Zod schema for validating the webhook payload           |
| `handler`     | **Yes**  | Function called when a valid webhook is received        |
| `description` | No       | Human-readable description                              |
| `verify`      | No       | Signature verification function (return `true`/`false`) |

***

## Webhook Handler Context

The handler receives a rich context object:

```typescript
handler: async ({
  payload,   // Validated webhook payload (typed from schema)
  config,    // Decrypted connector configuration
  context,   // From onContext hook (if defined)
  scope,     // Scope type recovered from webhook secret
  identity,  // Scope identifier recovered from webhook secret
  headers,   // Raw request headers
}) => {
  // payload.type — typed from schema
  // config.webhookSecret — available for API calls
  // scope, identity — the tenant that owns this webhook
}
```

***

## Webhook URL

When a connector with webhook support is connected, the manager automatically generates:

1. A **unique webhook secret** — used in the URL path to identify the tenant
2. A **webhook URL** — `{IGNITER_BASE_URL}/api/webhooks/{provider}/{secret}`

The secret is stored encrypted with the connector config.

```typescript
const result = await scoped.connect("stripe", { webhookSecret: "whsec_..." });

// result includes the webhook URL
console.log(result.webhookUrl);
// https://myapp.com/api/webhooks/stripe/sec_abc123
```

***

## Handling Webhooks

Handle incoming webhooks at the manager level:

```typescript
// app/api/webhooks/[provider]/[secret]/route.ts
export async function POST(
  req: NextRequest,
  { params }: { params: { provider: string; secret: string } },
) {
  const response = await connectors.handle("webhook", req as any);
  return response;
}
```

The manager:

1. Extracts the provider and secret from the URL
2. Looks up the connector record by provider + secret (via adapter)
3. Recovers the scope and identity from the record
4. Runs the `verify` function (if provided)
5. Validates the payload against the webhook schema
6. Runs the handler
7. Emits telemetry events

***

## Webhook Verification

The `verify` function authenticates the webhook. The request object contains:

```typescript
interface IgniterConnectorWebhookRequest {
  headers: unknown;   // Request headers (Headers object or plain object)
  body: unknown;      // Parsed JSON body
  rawBody?: string;   // Raw body string (for signature verification)
  method?: string;    // HTTP method
  url?: string;       // Request URL
}
```

### GitHub Webhook Verification

```typescript
verify: async (request, config) => {
  const crypto = await import("crypto");
  const sig = (request.headers as any)["x-hub-signature-256"] as string;
  const hmac = crypto.createHmac("sha256", config.webhookSecret);
  const digest = `sha256=${hmac.update(request.rawBody!).digest("hex")}`;
  return crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(digest),
  );
},
```

### Stripe Webhook Verification

```typescript
verify: async (request, config) => {
  const stripe = new Stripe(config.apiKey);
  const sig = (request.headers as any)["stripe-signature"] as string;
  try {
    stripe.webhooks.constructEvent(
      request.rawBody!,
      sig,
      config.webhookSecret,
    );
    return true;
  } catch {
    return false;
  }
},
```

***

## Webhook Events

Webhooks emit telemetry events automatically:

| Event               | When                                   |
| ------------------- | -------------------------------------- |
| `webhook.received`  | Request received (before verification) |
| `webhook.processed` | Handler completed successfully         |
| `webhook.failed`    | Verification failed or handler threw   |

***

## Webhook Metadata Tracking

The adapter tracks webhook metadata for monitoring:

```typescript
// Adapter stores:
{
  lastEventAt: Date,
  lastEventResult: "success" | "error",
  error?: string
}
```

Access this data via the connector instance:

```typescript
const instance = await scoped.get("stripe");
console.log(instance?.webhook);
// { secret: "sec_abc", url: "https://...", enabled: true }
```

***

## Real-World Example: Complete Stripe Webhook (Next.js)

### Connector Definition

```typescript
// connectors/stripe.ts
const stripeConnector = IgniterConnector.create()
  .withConfig(
    z.object({
      apiKey: z.string(),
      webhookSecret: z.string(),
    }),
  )
  .withWebhook({
    schema: z.object({
      type: z.string(),
      data: z.object({
        object: z.object({ id: z.string() }),
      }),
    }),
    handler: async ({ payload, config, identity }) => {
      switch (payload.type) {
        case "checkout.session.completed":
          await activateSubscription(identity, payload.data.object.id);
          break;
        case "customer.subscription.deleted":
          await cancelSubscription(identity);
          break;
      }
    },
    verify: async (request, config) => {
      const sig = (request.headers as any)["stripe-signature"];
      try {
        const stripe = require("stripe")(config.apiKey);
        stripe.webhooks.constructEvent(
          request.rawBody, sig, config.webhookSecret
        );
        return true;
      } catch { return false; }
    },
  })
  .addAction("createCheckout", {
    input: z.object({ priceId: z.string() }),
    handler: async ({ input, config }) => {
      // Create Stripe checkout session
    },
  })
  .build();
```

### Webhook Route

```typescript
// app/api/webhooks/[provider]/[secret]/route.ts
import { connectors } from "@/connectors/manager";

export async function POST(
  req: NextRequest,
  { params }: { params: { provider: string; secret: string } },
) {
  return connectors.handle("webhook", req as any);
}
```

**✅ That's it.** The manager handles everything: routing, verification, scope recovery, payload validation, and telemetry.

***

## Next Steps

* [OAuth](/docs/connectors/oauth) — OAuth 2.0 authentication flow
* [Telemetry](/docs/connectors/telemetry) — Webhook telemetry events
* [Events](/docs/connectors/events) — Subscribe to webhook events


---

# Comparison

> A comprehensive comparison of Igniter.js with popular TypeScript API frameworks including tRPC, Next.js Server Actions, Express, and Fastify.
URL: https://igniterjs.com/docs/core/comparison

## Overview

Choosing the right framework is crucial for your project's success. This guide compares **Igniter.js** with popular alternatives to help you make an informed decision.

<Callout type="info" title="Fair Comparison">
  This comparison aims to be fair and objective. Each framework has its strengths, and the "best" choice depends on your specific needs.
</Callout>

***

## Quick Comparison Table

| Feature                | Igniter.js   | tRPC             | Next.js SA     | Express      | Fastify      |
| ---------------------- | ------------ | ---------------- | -------------- | ------------ | ------------ |
| **Type Safety**        | ✅ End-to-end | ✅ End-to-end     | ⚠️ Partial     | ❌ Manual     | ❌ Manual     |
| **Code Generation**    | ❌ Not needed | ❌ Not needed     | ❌ Not needed   | ❌ Not needed | ❌ Not needed |
| **Standard HTTP**      | ✅ Full       | ⚠️ RPC only      | ⚠️ Limited     | ✅ Full       | ✅ Full       |
| **Framework Agnostic** | ✅ Yes        | ⚠️ Mostly        | ❌ Next.js only | ✅ Yes        | ✅ Yes        |
| **React Hooks**        | ✅ Built-in   | ✅ Adapter        | ✅ Built-in     | ❌ Manual     | ❌ Manual     |
| **OpenAPI**            | ✅ Auto       | ❌ External       | ❌ No           | ⚠️ Manual    | ⚠️ Manual    |
| **Real-time**          | ✅ SSE/WS     | ⚠️ Subscriptions | ❌ Limited      | ⚠️ Manual    | ⚠️ Manual    |
| **Middleware**         | ✅ Procedures | ✅ Yes            | ❌ Limited      | ✅ Yes        | ✅ Yes        |
| **Background Jobs**    | ✅ Built-in   | ❌ External       | ❌ External     | ❌ External   | ❌ External   |
| **Telemetry**          | ✅ Built-in   | ❌ External       | ❌ External     | ❌ External   | ❌ External   |
| **Learning Curve**     | 🟢 Low       | 🟢 Low           | 🟢 Low         | 🟡 Medium    | 🟡 Medium    |
| **Performance**        | ⚡ Fast       | ⚡ Fast           | ⚡ Fast         | ⚡ Fast       | ⚡⚡ Fastest   |

***

## Igniter.js vs tRPC

### Overview

Both provide **end-to-end type safety** without code generation. If you like tRPC, you'll feel at home with Igniter.js.

### Feature Comparison

| Feature           | Igniter.js                          | tRPC                    |
| ----------------- | ----------------------------------- | ----------------------- |
| Type Safety       | ✅ Full end-to-end                   | ✅ Full end-to-end       |
| HTTP Methods      | ✅ GET, POST, PUT, DELETE, PATCH     | ⚠️ RPC only             |
| REST Support      | ✅ Standard REST endpoints           | ❌ Not RESTful           |
| Framework Support | ✅ Next.js, Vite, Express, Bun, Deno | ⚠️ Primarily Next.js    |
| React Hooks       | ✅ Built-in                          | ✅ Via @trpc/react-query |
| OpenAPI Docs      | ✅ Auto-generated                    | ❌ Third-party tools     |
| Background Jobs   | ✅ Built-in (BullMQ)                 | ❌ External library      |
| Caching/Pub-Sub   | ✅ Built-in (Redis)                  | ❌ External library      |
| Telemetry         | ✅ Built-in (OpenTelemetry)          | ❌ External library      |
| Non-TS Clients    | ✅ Works with any HTTP client        | ⚠️ TypeScript only      |

### Code Comparison

<Tabs items={['Igniter.js', 'tRPC']}>
  <Tab value="Igniter.js">
    ```typescript
    // Define API with standard HTTP
    const userController = igniter.controller({
      name: 'Users',
      description: 'Manage user accounts and profiles',
      path: '/users',
      actions: {
        getById: igniter.query({
          name: 'Get User by ID',
          description: 'Retrieve a specific user by their ID',
          path: '/:id' as const,
          handler: async ({ request, response }) => {
            const user = await db.users.findUnique({
              where: { id: request.params.id }
            });
            return response.success({ user });
          }
        }),
        create: igniter.mutation({
          name: 'Create User',
          description: 'Create a new user account',
          path: '/',
          method: 'POST',
          body: z.object({
            name: z.string(),
            email: z.string().email()
          }),
          handler: async ({ request, response }) => {
            const user = await db.users.create({ 
              data: request.body 
            });
            return response.created({ user });
          }
        })
      }
    });

    // Client usage
    const { data } = await client.users.getById.query({ 
      params: { id: '123' } 
    });

    // ✅ Also works with curl, Postman, etc.
    // GET /api/v1/users/123
    ```
  </Tab>

  <Tab value="tRPC">
    ```typescript
    // Define API with RPC
    const userRouter = t.router({
      getById: t.procedure
        .input(z.object({ id: z.string() }))
        .query(async ({ input }) => {
          const user = await db.users.findUnique({ 
            where: { id: input.id } 
          });
          return { user };
        }),
      create: t.procedure
        .input(z.object({
          name: z.string(),
          email: z.string().email()
        }))
        .mutation(async ({ input }) => {
          const user = await db.users.create({ 
            data: input 
          });
          return { user };
        })
    });

    // Client usage
    const data = await trpc.users.getById.query({ id: '123' });

    // ⚠️ Only works with TypeScript clients
    // Not standard REST
    ```
  </Tab>
</Tabs>

### When to Choose tRPC

<Cards>
  <Card title="Next.js Only">
    You're building exclusively for Next.js
  </Card>

  <Card title="No REST Needed">
    You don't need standard REST endpoints
  </Card>

  <Card title="No External Clients">
    Only TypeScript clients will consume your API
  </Card>
</Cards>

### When to Choose Igniter.js

<Cards>
  <Card title="Standard HTTP">
    You need REST endpoints for external clients
  </Card>

  <Card title="Framework Flexibility">
    You want to work with Vite, Express, Bun, etc.
  </Card>

  <Card title="Rich Ecosystem">
    You need jobs, caching, telemetry built-in
  </Card>

  <Card title="OpenAPI Docs">
    You want auto-generated API documentation
  </Card>
</Cards>

***

## Igniter.js vs Next.js Server Actions

### Overview

Both provide type-safe client-server communication in React, but with very different approaches and capabilities.

### Feature Comparison

| Feature           | Igniter.js            | Next.js Server Actions         |
| ----------------- | --------------------- | ------------------------------ |
| Type Safety       | ✅ Full inference      | ⚠️ Partial (FormData casting)  |
| HTTP Methods      | ✅ All methods         | ❌ POST only                    |
| REST Endpoints    | ✅ Standard REST       | ❌ None                         |
| Framework Support | ✅ Framework agnostic  | ❌ Next.js only                 |
| External Clients  | ✅ Any HTTP client     | ❌ Next.js only                 |
| Real-time (SSE)   | ✅ Built-in            | ❌ Limited                      |
| WebSockets        | ✅ Supported           | ❌ Not supported                |
| Webhooks          | ✅ Standard routes     | ❌ Not suitable                 |
| Validation        | ✅ Zod/Valibot schemas | ⚠️ Manual                      |
| Testing           | ✅ Server-side caller  | ⚠️ Full Next.js context needed |

### Code Comparison

<Tabs items={['Igniter.js', 'Server Actions']}>
  <Tab value="Igniter.js">
    ```typescript
    // Server: Type-safe with validation
    const createUser = igniter.mutation({
      path: '/users',
      method: 'POST',
      body: z.object({
        name: z.string().min(2),
        email: z.string().email()
      }),
      handler: async ({ request, response }) => {
        // ✅ request.body is fully typed!
        const user = await db.users.create({ 
          data: request.body 
        });
        return response.created({ user });
      }
    });

    // Client: Fully typed
    const { data } = await client.users.create.mutate({
      body: { name: 'John', email: 'john@example.com' }
    });
    // ✅ data.user is fully typed!

    // ✅ Also works with external clients
    // POST /api/v1/users
    ```
  </Tab>

  <Tab value="Server Actions">
    ```typescript
    // Server: Manual type casting
    'use server'

    async function createUser(formData: FormData) {
      // ⚠️ Manual casting and validation
      const name = formData.get('name') as string;
      const email = formData.get('email') as string;
      
      // Manual validation
      if (!name || name.length < 2) {
        throw new Error('Name too short');
      }
      
      const user = await db.users.create({ 
        data: { name, email } 
      });
      return user;
    }

    // Client: Limited type inference
    const user = await createUser(formData);
    // ⚠️ Type not automatically inferred

    // ❌ Can't call from external clients
    // ❌ No REST endpoint
    ```
  </Tab>
</Tabs>

### When to Choose Server Actions

<Cards>
  <Card title="Next.js Exclusive">
    Building only for Next.js with RSC
  </Card>

  <Card title="Simple Forms">
    Primary use case is form submissions
  </Card>

  <Card title="No External API">
    Don't need external clients or webhooks
  </Card>
</Cards>

### When to Choose Igniter.js

<Cards>
  <Card title="REST API">
    Need standard REST endpoints
  </Card>

  <Card title="Framework Agnostic">
    Want to use Vite, Remix, or other frameworks
  </Card>

  <Card title="External Clients">
    Mobile apps, webhooks, third-party integrations
  </Card>

  <Card title="Real-time">
    Need SSE, WebSockets, or Pub/Sub
  </Card>
</Cards>

***

## Igniter.js vs Express.js

### Overview

Express is the most popular Node.js framework, while Igniter.js is a modern TypeScript-first alternative with built-in type safety.

### Feature Comparison

| Feature           | Igniter.js               | Express.js                     |
| ----------------- | ------------------------ | ------------------------------ |
| Type Safety       | ✅ Automatic inference    | ❌ Manual TypeScript            |
| Validation        | ✅ Built-in (Zod/Valibot) | ❌ External (express-validator) |
| Client Generation | ✅ Automatic              | ❌ Manual                       |
| React Hooks       | ✅ Built-in               | ❌ Manual implementation        |
| OpenAPI Docs      | ✅ Auto-generated         | ⚠️ Manual (Swagger)            |
| Background Jobs   | ✅ Built-in               | ❌ External library             |
| Telemetry         | ✅ Built-in               | ❌ External (Morgan, etc.)      |
| Ecosystem         | 🟡 Growing               | ⚡ Massive                      |
| Maturity          | 🟡 New                   | ⚡⚡⚡ Very mature                |
| Learning Curve    | 🟢 Low                   | 🟢 Low                         |

### Code Comparison

<Tabs items={['Igniter.js', 'Express.js']}>
  <Tab value="Igniter.js">
    ```typescript
    // Route with automatic validation & typing
    const createUser = igniter.mutation({
      path: '/users',
      method: 'POST',
      body: z.object({
        name: z.string().min(2),
        email: z.string().email(),
        age: z.number().min(18)
      }),
      handler: async ({ request, response }) => {
        // ✅ request.body is validated and typed
        const { name, email, age } = request.body;
        
        const user = await db.users.create({ 
          data: { name, email, age } 
        });
        
        return response.created({ user });
      }
    });

    // Client: Automatic type-safe hooks
    const { mutate, isLoading } = client.users.create.useMutation();

    await mutate({ 
      body: { name: 'John', email: 'john@example.com', age: 25 } 
    });
    ```
  </Tab>

  <Tab value="Express.js">
    ```typescript
    import { body, validationResult } from 'express-validator';

    // Route with manual validation
    app.post('/users',
      // Manual validation rules
      body('name').isString().isLength({ min: 2 }),
      body('email').isEmail(),
      body('age').isInt({ min: 18 }),
      async (req, res) => {
        // Manual error checking
        const errors = validationResult(req);
        if (!errors.isEmpty()) {
          return res.status(400).json({ errors: errors.array() });
        }
        
        // ⚠️ Manual type casting
        const { name, email, age } = req.body as {
          name: string;
          email: string;
          age: number;
        };
        
        const user = await db.users.create({ 
          data: { name, email, age } 
        });
        
        res.status(201).json({ user });
      }
    );

    // Client: Manual fetch
    const response = await fetch('/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name: 'John', email: 'john@example.com', age: 25 })
    });

    const data = await response.json() as { user: User };
    ```
  </Tab>
</Tabs>

### When to Choose Express

<Cards>
  <Card title="Huge Ecosystem">
    Need access to thousands of Express plugins
  </Card>

  <Card title="Team Experience">
    Team is already experienced with Express
  </Card>

  <Card title="Migration">
    Migrating from existing Express codebase
  </Card>

  <Card title="Maximum Control">
    Need low-level HTTP control
  </Card>
</Cards>

### When to Choose Igniter.js

<Cards>
  <Card title="Type Safety">
    Want automatic end-to-end type safety
  </Card>

  <Card title="Modern DX">
    Prefer modern TypeScript-first development
  </Card>

  <Card title="Auto Client">
    Need automatic client generation
  </Card>

  <Card title="Built-in Tools">
    Want validation, jobs, telemetry out of the box
  </Card>
</Cards>

***

## Igniter.js vs Fastify

### Overview

Fastify is the fastest Node.js framework, optimized for performance. Igniter.js prioritizes developer experience while maintaining excellent performance.

### Feature Comparison

| Feature           | Igniter.js            | Fastify            |
| ----------------- | --------------------- | ------------------ |
| Performance       | ⚡⚡ Very fast          | ⚡⚡⚡ Fastest        |
| Type Safety       | ✅ Automatic inference | ⚠️ Manual generics |
| Validation        | ✅ Zod/Valibot         | ✅ JSON Schema      |
| Client Generation | ✅ Automatic           | ❌ Manual           |
| React Hooks       | ✅ Built-in            | ❌ External         |
| Schema Required   | ⚠️ Optional           | ✅ Recommended      |
| OpenAPI           | ✅ Auto-generated      | ⚠️ Via plugin      |
| DX                | ⚡ Excellent           | 🟡 Good            |
| Ecosystem         | 🟡 Growing            | ⚡ Large            |
| Plugin System     | ✅ Yes                 | ⚡⚡ Very rich       |

### Code Comparison

<Tabs items={['Igniter.js', 'Fastify']}>
  <Tab value="Igniter.js">
    ```typescript
    // Automatic type inference
    const getUser = igniter.query({
      name: 'Get User',
      description: 'Retrieve a specific user by ID',
      path: '/users/:id' as const,
      handler: async ({ request, response }) => {
        // ✅ request.params.id is automatically typed
        const user = await db.users.findUnique({ 
          where: { id: request.params.id } 
        });
        
        if (!user) {
          return response.notFound('User not found');
        }
        
        return response.success({ user });
      }
    });

    // Client: Automatic hooks
    const { data, isLoading } = client.users.getById.useQuery({
      params: { id: '123' }
    });
    ```
  </Tab>

  <Tab value="Fastify">
    ```typescript
    // Manual type definitions
    interface GetUserParams {
      id: string;
    }

    interface GetUserReply {
      user: User;
    }

    fastify.get<{
      Params: GetUserParams;
      Reply: GetUserReply;
    }>('/users/:id', {
      schema: {
        params: {
          type: 'object',
          properties: {
            id: { type: 'string' }
          }
        },
        response: {
          200: {
            type: 'object',
            properties: {
              user: { type: 'object' }
            }
          }
        }
      }
    }, async (request, reply) => {
      const user = await db.users.findUnique({ 
        where: { id: request.params.id } 
      });
      
      if (!user) {
        return reply.code(404).send({ error: 'User not found' });
      }
      
      return { user };
    });

    // Client: Manual fetch
    const response = await fetch('/users/123');
    const data = await response.json() as GetUserReply;
    ```
  </Tab>
</Tabs>

### When to Choose Fastify

<Cards>
  <Card title="Maximum Performance">
    Performance is the absolute top priority
  </Card>

  <Card title="JSON Schema">
    Prefer JSON Schema over Zod
  </Card>

  <Card title="Rich Plugins">
    Need access to Fastify's plugin ecosystem
  </Card>

  <Card title="Low-Level Control">
    Need fine-grained HTTP control
  </Card>
</Cards>

### When to Choose Igniter.js

<Cards>
  <Card title="Better DX">
    Developer experience matters more than raw speed
  </Card>

  <Card title="Auto Types">
    Want automatic type inference
  </Card>

  <Card title="React Integration">
    Need built-in React hooks
  </Card>

  <Card title="Zod/Valibot">
    Prefer Zod over JSON Schema
  </Card>
</Cards>

***

## Summary

Choose **Igniter.js** if you want:

* ✅ **End-to-end type safety** without code generation
* ✅ **Framework flexibility** (not locked to Next.js)
* ✅ **Standard HTTP/REST** support
* ✅ **Built-in ecosystem** (jobs, caching, telemetry, bots)
* ✅ **Excellent DX** with automatic client generation
* ✅ **Production-ready** features out of the box

<Callout type="success" title="Ready to Start?">
  Igniter.js combines the best of all worlds: tRPC's type safety, Express's flexibility, and a rich built-in ecosystem.

  [Get Started →](/docs/installation)
</Callout>


---

# Introduction

> The first AI-native TypeScript framework with built-in training for 15+ Code Agents. Built for Code Agents, perfected for developers.
URL: https://igniterjs.com/docs/core

Igniter.js is **the first AI-native TypeScript framework** designed from the ground up for the future of software development—where humans and AI collaborate seamlessly. It provides end-to-end type safety, real-time capabilities, background jobs, and a predictable architecture that both developers and AI agents can easily understand and modify.

## Built for Code Agents, Perfected for Developers

Unlike traditional frameworks that treat AI integration as an afterthought, Igniter.js was architected from day one with **AI-first principles**. Every design decision—from the feature-sliced architecture to the explicit type system—creates a **low-entropy environment** that makes it dramatically easier for Code Agents like Cursor, Claude Code, GitHub Copilot, and Gemini CLI to understand, navigate, and modify your codebase.

The framework eliminates common sources of confusion for AI agents: implicit behaviors, magic conventions, scattered configuration, and complex inheritance hierarchies. Instead, it embraces **explicit over implicit**, **composition over inheritance**, and **feature-based organization** that mirrors how humans naturally think about business logic.

What does this mean in practice? When you ask Claude Code to "add authentication to the users endpoint," it doesn't need to hunt through multiple files, decipher framework magic, or guess at conventions. It sees a clear, predictable structure where every feature is self-contained, every dependency is explicit, and every type is precisely defined. The AI can confidently make changes knowing exactly what will break and what won't.

But being AI-native doesn't mean sacrificing developer experience. In fact, the same principles that make code easy for AI to understand—clarity, explicitness, and strong typing—make it a joy for humans to work with too. You get exceptional IntelliSense, instant error detection, and a framework that guides you toward best practices naturally.

```typescript
// Crystal-clear structure that both humans and AI understand instantly
export const users = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    getById: igniter.query({
      name: 'Get User by ID',
      description: 'Retrieve a specific user by their ID',
      path: '/:id' as const,
      handler: async ({ params }) => {
        const user = await db.users.findUnique({ where: { id: params.id } })
        return response.success({ user })
      }
    })
  }
})

// Client code is automatically type-safe—no configuration needed
const { user } = await api.users.getById.query({ id: '123' })
//     ^? User - TypeScript knows the exact type!
```

## Why Igniter.js?

<Accordions>
  <Accordion title="AI-Native Architecture">
    Built from the ground up for Code Agents with a low-entropy, predictable structure. Every file, every pattern, every convention is designed to be instantly understandable by both humans and AI.

    **What makes it AI-friendly?**

    * **Feature-Sliced Architecture** - Business logic organized by features, not technical layers
    * **Explicit Type System** - Zero magic, everything is typed and traceable
    * **Self-Contained Modules** - Each feature includes its routes, controllers, and types
    * **Predictable Patterns** - Consistent conventions across the entire codebase
    * **Low Coupling** - Changes are localized and AI can reason about impact

    When you ask Cursor to "add rate limiting to the auth endpoint," it knows exactly where to look, what to modify, and what tests to update—no guessing required.
  </Accordion>

  <Accordion title="End-to-End Type Safety">
    Every request and response is fully typed from server to client. No code generation, no manual type definitions, no runtime overhead—just pure TypeScript inference.

    ```typescript
    // Change the server response
    return response.success({ user, posts }) // Added posts!

    // TypeScript immediately updates the client
    const data = await api.users.getById.query({ id: '123' })
    //    ^? { user: User, posts: Post[] } ✅
    ```

    If you change an endpoint's return type, add a parameter, or modify validation rules, TypeScript catches breaking changes instantly across your entire codebase. Your IDE becomes a safety net that prevents runtime errors before they happen.
  </Accordion>

  <Accordion title="Framework Agnostic">
    Built on Web Standards (Request/Response) to work anywhere TypeScript runs:

    * **Next.js** - Full-stack React with SSR and API routes
    * **Express** - Traditional Node.js web framework
    * **Hono** - Ultrafast edge runtime framework
    * **Bun** - All-in-one JavaScript runtime
    * **Deno** - Secure-by-default runtime

    Same code, same types, different runtime. Choose what works best for your deployment target and switch later if needed—your business logic stays unchanged.
  </Accordion>

  <Accordion title="Production Ready">
    Everything you need to build production applications:

    * **Real-time Updates** - Built-in SSE and WebSocket support
    * **Background Jobs** - BullMQ integration for async processing
    * **Caching** - Redis adapter for high-performance caching
    * **Observability** - OpenTelemetry integration out of the box
    * **API Documentation** - Auto-generated OpenAPI specs
    * **Testing** - Server-side caller for fast, type-safe tests

    Start with the core and add features as you scale. No need to retrofit critical functionality later.
  </Accordion>
</Accordions>

## Get Started

Choose your framework to start building:

<Cards>
  <Card title="Next.js" description="Full-stack React framework with SSR and API routes" href="/docs/installation/nextjs" icon={<NextJsIcon className="size-6" />} />

  <Card title="Vite" description="Lightning-fast build tool for modern web projects" href="/docs/installation/vite" icon={<ViteIcon className="size-6" />} />

  <Card title="Express" description="Fast, unopinionated web framework for Node.js" href="/docs/installation/express" icon={<ExpressIcon className="size-6" />} />

  <Card title="Bun" description="Fast all-in-one JavaScript runtime and toolkit" href="/docs/installation/bun" icon={<BunIcon className="size-6" />} />

  <Card title="Deno" description="Secure runtime for JavaScript and TypeScript" href="/docs/installation/deno" icon={<DenoIcon className="size-6" />} />
</Cards>

Or use the CLI for a guided setup:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest init
    ```
  </Tab>
</Tabs>

<Callout type="info" title="Comparing Frameworks?">
  See how Igniter.js compares to tRPC, Next.js Server Actions, and other frameworks.

  [→ Framework Comparison](/docs/comparison)
</Callout>

***

## AI Tooling

Igniter.js provides a complete AI development ecosystem that transforms how you build applications.

### Lia - Your AI Development Partner

**Lia** is a specialized Code Agent trained exclusively for the Igniter.js ecosystem. Unlike generic AI assistants that struggle with framework-specific patterns, Lia is purpose-built to understand every aspect of Igniter.js—from architecture decisions to testing strategies.

When you install Lia in your project, she replaces the default behavior of Code Agents like Cursor, Claude Code, or GitHub Copilot with deep knowledge of:

* **Igniter.js Architecture** - Feature-based design, controller patterns, and type-safe APIs
* **Development Workflows** - From scaffolding to deployment, following best practices
* **Testing Strategies** - Unit tests, integration tests, and E2E testing patterns
* **Debugging Techniques** - Advanced diagnostics using MCP Server tools

What makes Lia special is her ability to not just write code, but to **validate, debug, and test** what she creates. She can:

* Scaffold complete features following Igniter.js conventions
* Debug type errors and suggest fixes with context-aware solutions
* Run and analyze test results to ensure quality
* Investigate code using AST parsing and semantic search
* Create GitHub issues and explore library source code
* Manage tasks with built-in project management tools

[→ Learn more about Lia](/docs/ai/lia)

### MCP Server - Lia's Toolbox

The **Igniter.js MCP Server** is what powers Lia's advanced capabilities. It's a collection of specialized tools that transform your API into an AI-accessible workspace, enabling Lia to perform complex development tasks autonomously.

<Accordions>
  <Accordion title="Development Tools">
    These tools enable Lia to scaffold and build features following Igniter.js conventions. She can generate complete, production-ready code structures without requiring manual boilerplate.

    * Scaffold controllers, actions, and procedures
    * Add adapters (Redis, BullMQ, OpenTelemetry)
    * Generate type-safe clients and schemas
    * Create middleware and custom procedures
  </Accordion>

  <Accordion title="Debugging & Analysis">
    Lia uses these tools to understand your codebase deeply and diagnose issues with precision. She can analyze dependencies, parse TypeScript AST, and validate type safety across your entire API.

    * Validate API endpoints and type safety
    * Analyze file dependencies and imports
    * Parse TypeScript AST for code understanding
    * Execute CLI commands and capture output
  </Accordion>

  <Accordion title="Testing & Quality">
    Quality assurance tools that allow Lia to not just write code, but verify it works correctly. She can run tests, analyze coverage, and explain failures with detailed context.

    * Run unit and integration tests
    * Analyze test coverage and results
    * Diagnose failures with detailed context
    * Generate test cases for new features
  </Accordion>

  <Accordion title="Project Management">
    These tools help Lia manage the entire development lifecycle, from planning to documentation. She can track tasks, create issues, and explore external codebases to understand dependencies.

    * Create and manage tasks
    * Track progress and blockers
    * Generate documentation
    * Integrate with GitHub (issues, PRs, code exploration)
  </Accordion>

  <Accordion title="Memory & Context">
    Lia's learning system that enables her to improve over time. She stores insights, recalls past decisions, and builds a knowledge base specific to your project.

    * Store insights and learnings
    * Recall past decisions and patterns
    * Build knowledge base over time
    * Share context across development sessions
  </Accordion>
</Accordions>

[→ Explore MCP Server tools](/docs/ai/mcp-server)

### Getting Started with Lia

Installing Lia is simple. Use the Igniter.js CLI to set up Lia in your preferred Code Agent:

<Tabs items={['Cursor', 'Claude Desktop', 'GitHub Copilot']}>
  <Tab value="Cursor">
    ```bash
    npx @igniter-js/cli@latest lia --cursor
    ```

    This configures Lia in Cursor by:

    1. Adding the MCP Server to your Cursor settings
    2. Installing Code Agent training files (`.cursor/rules/`)
    3. Creating the `AGENTS.md` file with Lia's identity

    Restart Cursor and Lia will be active, ready to help you build.
  </Tab>

  <Tab value="Claude Desktop">
    ```bash
    npx @igniter-js/cli@latest lia --claude
    ```

    Adds Lia's MCP Server to Claude Desktop configuration. After restarting Claude, you can ask Lia to scaffold features, debug issues, or analyze your codebase.
  </Tab>

  <Tab value="GitHub Copilot">
    ```bash
    npx @igniter-js/cli@latest lia --copilot
    ```

    Configures Lia for GitHub Copilot with training files and MCP integration. Enhances Copilot's understanding of Igniter.js patterns.
  </Tab>
</Tabs>

### Using Lia in Your Project

Once installed, Lia becomes your intelligent pair programmer. Here are examples of what you can ask:

<Accordions>
  <Accordion title="Feature Development">
    Lia can scaffold complete features with all necessary components—controllers, actions, types, and tests—following Igniter.js best practices.

    **Examples:**

    * "Create a users controller with CRUD operations and authentication"
    * "Add Redis caching to the posts endpoint"
    * "Set up background jobs for email notifications"
  </Accordion>

  <Accordion title="Debugging & Analysis">
    When you encounter errors or need to understand your codebase better, Lia can analyze dependencies, trace types, and explain issues with full context.

    **Examples:**

    * "Why is this type error happening in my controller?"
    * "Analyze the dependencies of the auth feature"
    * "Show me all actions that use the database context"
  </Accordion>

  <Accordion title="Testing & Quality">
    Lia can write tests, run them, and explain failures. She understands your testing strategy and generates tests that match your project's conventions.

    **Examples:**

    * "Run tests for the users controller and explain any failures"
    * "Generate integration tests for the authentication flow"
    * "Check if all endpoints have proper error handling"
  </Accordion>

  <Accordion title="Project Management">
    Beyond coding, Lia helps with planning and organization. She can create issues, explore external libraries, and manage your development workflow.

    **Examples:**

    * "Create a GitHub issue for adding rate limiting"
    * "Show me the implementation of `igniter.query` in the core package"
    * "What are the current tasks and their status?"
  </Accordion>
</Accordions>

Lia understands the full context of your project and delivers production-ready code that follows Igniter.js best practices.

### LLMs.txt

Igniter.js website exposes multiple llms-readable documentation formats that help AI understand your API structure and how to interact with it.

#### Main Entry Point

**`/llms.txt`** - A comprehensive index that provides:

* Overview of the Igniter.js framework
* Site structure and content organization
* Links to all available content types
* Instructions on how to access individual pages

Visit [https://igniterjs.com/llms.txt](https://igniterjs.com/llms.txt) to see the complete index.

#### Full Content Files

For AI models that need complete documentation in a single file:

* **`/llms-full.txt`** - Complete documentation from all content types (blog, docs, learn, templates, showcase, changelog)
* **`/llms/blog/full.txt`** - All blog posts and articles
* **`/llms/docs/full.txt`** - Complete framework documentation
* **`/llms/learn/full.txt`** - All learn course chapters
* **`/llms/templates/full.txt`** - All starter templates
* **`/llms/showcase/full.txt`** - All showcase projects
* **`/llms/changelog/full.txt`** - All version updates and release notes

#### Individual Pages

Any page can be accessed in markdown format by appending `.mdx` to the URL:

* `/docs/core/quick-start.mdx` - Documentation page as markdown
* `/blog/introducing-igniter-js.mdx` - Blog post as markdown
* `/learn/course/01-creating-your-project.mdx` - Learn chapter as markdown

This allows AI models to fetch specific pages on-demand, reducing token usage while maintaining full context when needed.

#### Other Formats

* **`/rss`** - RSS feed with all content types
* **`/rss/[type]`** - RSS feed for specific content type (blog, docs, learn, etc.)
* **`/sitemap.xml`** - XML sitemap with all pages

All these formats are designed to make Igniter.js documentation easily accessible to AI models, enabling better code generation, documentation understanding, and API interaction.


---

# Quick Start

> Build your first type-safe API with Igniter.js in 10 minutes. Learn the core concepts by creating a complete user management API.
URL: https://igniterjs.com/docs/core/quick-start

## What You'll Build

In this guide, you'll create a fully functional user management API with:

* ✅ **Type-safe endpoints** for CRUD operations
* ✅ **Automatic validation** with Zod schemas
* ✅ **Full type inference** from server to client
* ✅ **React hooks** for data fetching

By the end, you'll have a working API and understand the core Igniter.js patterns.

## Prerequisites

Before starting, ensure you have:

* Igniter.js installed ([Installation Guide](/docs/installation))
* Basic TypeScript knowledge
* A code editor with TypeScript support

## Quick Start Tutorial

<Card title="Complete Igniter.js Setup Guide">
  <Steps>
    <Step>
      ### Create Your First Router

      Let's start by creating the core Igniter instance. This is where you configure your application's context and settings.

      Create `src/igniter.ts`:

      ```typescript
      import { Igniter } from '@igniter-js/core';

      // Define your application context type
      export interface AppContext {
        db: {
          users: Array<{ id: string; name: string; email: string }>;
        };
      }

      // Create context factory function
      export function createIgniterAppContext(): AppContext {
        return {
          db: {
            users: [] // In a real app, this would be your database connection
          }
        };
      }

      // Create and configure your Igniter instance
      export const igniter = Igniter
        .context(createIgniterAppContext())
        .config({
          baseURL: 'http://localhost:3000',
          basePATH: '/api/v1'
        })
        .create();
      ```

      <Callout type="info" title="What's Happening Here?">
        * **`Igniter.context(createIgniterAppContext())`** - Passes the context factory function to define your application's global context
        * **`.config()`** - Sets the base URL and path for your API
        * **`.create()`** - Creates the configured Igniter instance with all methods available
      </Callout>
    </Step>

    <Step>
      ### Define a Controller

      Controllers group related actions together. Let's create a user controller.

      Create `src/features/user/user.controller.ts`:

      ```typescript
      import { igniter } from '@/igniter';
      import { z } from 'zod';

      // Define validation schemas
      const UserSchema = z.object({
        id: z.string(),
        name: z.string().min(2),
        email: z.string().email()
      });

      const CreateUserSchema = z.object({
        name: z.string().min(2),
        email: z.string().email()
      });

      // Create the controller
      export const userController = igniter.controller({
        name: 'Users',
        description: 'Manage user accounts and profiles',
        path: '/users',
        actions: {
          // We'll add actions in the next step
        }
      });
      ```

      <Callout type="info">
        Controllers use the `path` property to prefix all their actions. All actions inside `/users` controller will be prefixed with `/users`.
      </Callout>

      <Callout type="success" title="OpenAPI Documentation">
        The `name` and `description` properties are crucial for generating comprehensive OpenAPI specifications for your API. They enable the CLI to create detailed documentation that powers **Igniter Studio** (our interactive API playground), making your API much more discoverable and user-friendly.
      </Callout>
    </Step>

    <Step>
      ### Create Actions

      Actions are the actual API endpoints. Igniter.js has two types:

      * **Query** - For reading data (GET requests)
      * **Mutation** - For modifying data (POST, PUT, DELETE, PATCH)

      ### Query Action (GET)

      Add a query action to list all users:

      ```typescript
      export const userController = igniter.controller({
        path: '/users',
        actions: {
          list: igniter.query({
            name: 'List Users',
            description: 'Retrieve a list of all users',
            path: '/',
            handler: async ({ context, response }) => {
              // Access your context (typed automatically!)
              const users = context.db.users;

              // Return a success response
              return response.success({ users });
            }
          }),
        }
      });
      ```

      ### Mutation Action (POST)

      Add a mutation to create a new user:

      ```typescript
      export const userController = igniter.controller({
        path: '/users',
        actions: {
          list: igniter.query({
            path: '/',
            handler: async ({ context, response }) => {
              const users = context.db.users;
              return response.success({ users });
            }
          }),
          
          create: igniter.mutation({
            name: 'Create User',
            description: 'Create a new user account',
            path: '/',
            method: 'POST',
            body: CreateUserSchema, // ← Validation schema
            handler: async ({ request, context, response }) => {
              // request.body is automatically validated and typed!
              const newUser = {
                id: crypto.randomUUID(),
                name: request.body.name,
                email: request.body.email
              };
              
              context.db.users.push(newUser);
              
              // Return created status with the new user
              return response.created({ user: newUser });
            }
          }),
        }
      });
      ```

      <Callout type="success" title="Type Safety in Action">
        Notice how `request.body.name` and `request.body.email` are fully typed! TypeScript knows their exact types from the `CreateUserSchema`.
      </Callout>

      ### Path Parameters

      Let's add an action to get a single user by ID:

      ```typescript
      getById: igniter.query({
        name: 'Get User by ID',
        description: 'Retrieve a specific user by their ID',
        path: '/:id' as const, // ← Path parameter with 'as const' for proper type inference
        handler: async ({ request, context, response }) => {
          // request.params.id is automatically typed as string
          const user = context.db.users.find(u => u.id === request.params.id);
          
          if (!user) {
            return response.notFound({ message: 'User not found' });
          }
          
          return response.success({ user });
        }
      }),
      ```

      ### Query Parameters

      Add a search action with query parameters:

      ```typescript
      search: igniter.query({
        name: 'Search Users',
        description: 'Search users by name with optional limit',
        path: '/search',
        query: z.object({
          q: z.string().min(1),
          limit: z.number().optional()
        }),
        handler: async ({ request, context, response }) => {
          // request.query is validated and typed!
          const { q, limit = 10 } = request.query;
          
          const results = context.db.users
            .filter(u => u.name.toLowerCase().includes(q.toLowerCase()))
            .slice(0, limit);
          
          return response.success({ users: results, query: q });
        }
      }),
      ```
    </Step>

    <Step>
      ### Set Up the Client

      Now let's create a type-safe client to call your API from the frontend.

      Create `src/lib/api-client.ts`:

      ```typescript
      import { createIgniterClient } from '@igniter-js/core/client';
      import { AppRouter } from '@/igniter.router';

      export const client = createIgniterClient<typeof AppRouter>({
        baseURL: 'http://localhost:3000',
        basePATH: '/api/v1',
        router: AppRouter
      });
      ```

      <Callout type="info" title="Type Inference Magic">
        The `createIgniterClient` function infers all your API types automatically. You don't need to manually define any types!
      </Callout>
    </Step>

    <Step>
      ### Make Your First Request

      ### Server-Side (Using Caller)

      For server-side rendering or testing, use the built-in caller:

      ```typescript
      // In a Next.js Server Component or API route
      import { AppRouter } from '@/igniter.router';

      export async function UsersList() {
        // Direct server-side call - no HTTP!
        const { data } = await AppRouter.caller.users.list.query();
        
        return (
          <ul>
            {data.users.map(user => (
              <li key={user.id}>{user.name}</li>
            ))}
          </ul>
        );
      }
      ```

      ### Client-Side (Browser)

      Using React hooks for automatic caching and state management:

      ```typescript
      'use client';

      import { client } from '@/lib/api-client';

      export function UsersListClient() {
        // Fully typed hook with loading states
        const { data, isLoading, error } = client.users.list.useQuery();
        
        if (isLoading) return <div>Loading...</div>;
        if (error) return <div>Error: {error.message}</div>;
        
        return (
          <ul>
            {data.users.map(user => (
              <li key={user.id}>{user.name}</li>
            ))}
          </ul>
        );
      }
      ```

      ### Mutations (Create User)

      ```typescript
      'use client';

      import { client } from '@/lib/api-client';
      import { useState } from 'react';

      export function CreateUserForm() {
        const [name, setName] = useState('');
        const [email, setEmail] = useState('');
        
        const { mutate, isPending } = client.users.create.useMutation({
          onSuccess: (data) => {
            console.log('User created:', data.user);
            // Reset form
            setName('');
            setEmail('');
          }
        });
        
        const handleSubmit = (e: React.FormEvent) => {
          e.preventDefault();
          // Fully typed mutation!
          mutate({ body: { name, email } });
        };
        
        return (
          <form onSubmit={handleSubmit}>
            <input 
              value={name} 
              onChange={e => setName(e.target.value)}
              placeholder="Name"
            />
            <input 
              value={email} 
              onChange={e => setEmail(e.target.value)}
              placeholder="Email"
              type="email"
            />
            <button type="submit" disabled={isPending}>
              {isPending ? 'Creating...' : 'Create User'}
            </button>
          </form>
        );
      }
      ```
    </Step>
  </Steps>
</Card>

## Complete Example

Here's the full user controller with all CRUD operations:

<Accordions>
  <Accordion title="Complete user.controller.ts">
    ```typescript
    import { igniter } from '@/igniter';
    import { z } from 'zod';

    const UserSchema = z.object({
      id: z.string(),
      name: z.string().min(2),
      email: z.string().email()
    });

    const CreateUserSchema = UserSchema.omit({ id: true });
    const UpdateUserSchema = CreateUserSchema.partial();

    export const userController = igniter.controller({
      name: 'Users',
      description: 'Manage user accounts and profiles',
      path: '/users',
      actions: {
        // List all users
        list: igniter.query({
          name: 'List Users',
          description: 'Retrieve a list of all users',
          path: '/',
          handler: async ({ context, response }) => {
            return response.success({ users: context.db.users });
          }
        }),

        // Get user by ID
        getById: igniter.query({
          name: 'Get User by ID',
          description: 'Retrieve a specific user by their ID',
          path: '/:id' as const,
          handler: async ({ request, context, response }) => {
            const user = context.db.users.find(u => u.id === request.params.id);
            
            if (!user) {
              return response.notFound({ message: 'User not found' });
            }
            
            return response.success({ user });
          }
        }),
        
        // Search users
        search: igniter.query({
          name: 'Search Users',
          description: 'Search users by name with optional limit',
          path: '/search',
          query: z.object({
            q: z.string().min(1),
            limit: z.number().optional()
          }),
          handler: async ({ request, context, response }) => {
            const { q, limit = 10 } = request.query;
            
            const results = context.db.users
              .filter(u => u.name.toLowerCase().includes(q.toLowerCase()))
              .slice(0, limit);
            
            return response.success({ users: results });
          }
        }),
        
        // Create user
        create: igniter.mutation({
          name: 'Create User',
          description: 'Create a new user account',
          path: '/',
          method: 'POST',
          body: CreateUserSchema,
          handler: async ({ request, context, response }) => {
            const newUser = {
              id: crypto.randomUUID(),
              ...request.body
            };
            
            context.db.users.push(newUser);
            return response.created({ user: newUser });
          }
        }),
        
        // Update user
        update: igniter.mutation({
          name: 'Update User',
          description: 'Update an existing user by ID',
          path: '/:id' as const,
          method: 'PUT',
          body: UpdateUserSchema,
          handler: async ({ request, context, response }) => {
            const userIndex = context.db.users.findIndex(
              u => u.id === request.params.id
            );
            
            if (userIndex === -1) {
              return response.notFound({ message: 'User not found' });
            }
            
            context.db.users[userIndex] = {
              ...context.db.users[userIndex],
              ...request.body
            };
            
            return response.success({ user: context.db.users[userIndex] });
          }
        }),
        
        // Delete user
        delete: igniter.mutation({
          name: 'Delete User',
          description: 'Delete a user by ID',
          path: '/:id' as const,
          method: 'DELETE',
          handler: async ({ request, context, response }) => {
            const userIndex = context.db.users.findIndex(
              u => u.id === request.params.id
            );
            
            if (userIndex === -1) {
              return response.notFound({ message: 'User not found' });
            }
            
            context.db.users.splice(userIndex, 1);
            return response.success({ message: 'User deleted' });
          }
        }),
      }
    });
    ```
  </Accordion>
</Accordions>

## What You've Learned

Congratulations! You've built your first Igniter.js API. You now understand:

✅ **The Builder Pattern** - How to configure your Igniter instance\
✅ **Controllers** - How to group related endpoints\
✅ **Actions** - How to create queries and mutations\
✅ **Validation** - How to use Zod schemas for type-safe input\
✅ **Client** - How to consume your API with full type safety\
✅ **React Hooks** - How to use `useQuery` and `useMutation`

***

## Development Workflow

### Required Steps for Full-Stack Development

<Callout type="error">
  **Development Workflow:** When building full-stack applications, follow this sequence:

  1. **Create/Modify API** (controllers, actions)
  2. **Generate Schema** (required for client to work)
  3. **Use Client** in frontend components
</Callout>

### When to Generate Schema

<Callout type="error">
  **Critical:** You MUST run schema generation BEFORE using the client in your frontend. The client depends on the generated schema to function correctly.
</Callout>

<Callout type="info">
  Run this command whenever you modify your API structure (add/remove/modify controllers or actions) OR before using the client for the first time.
</Callout>

When you add a new controller, action, or modify existing ones:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="maintenance-schema">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest generate schema
    ```
  </Tab>
</Tabs>

This regenerates:

* `src/igniter.schema.ts` - Updated type definitions for your client
* `src/docs/openapi.json` - Updated OpenAPI specification

### Generate Documentation

To update your API documentation and playground:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="maintenance-docs">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest generate docs
    ```
  </Tab>
</Tabs>

***

## Next Steps

Now that you understand the basics, explore these topics:

<Steps>
  <Step>
    ### Learn the Builder Pattern

    Understand how to configure context, store, jobs, and more

    [→ Builder Documentation](/docs/builder)
  </Step>

  <Step>
    ### Add Middleware with Procedures

    Create reusable authentication and validation logic

    [→ Procedures Guide](/docs/procedures)
  </Step>

  <Step>
    ### Explore Advanced Features

    Real-time updates, plugins, error handling, and more

    [→ Advanced Features](/docs/validation)
  </Step>

  <Step>
    ### Deploy to Production

    Learn best practices for production deployment

    [→ Deployment Guide](/docs/deployment)
  </Step>
</Steps>

## Common Patterns

### Custom Response Types

You can return any data structure:

```typescript
handler: async ({ response }) => {
  // Standard success with data
  return response.success({ users: [] });
  
  // Created (201)
  return response.created({ user: newUser });
  
  // Not found (404)
  return response.notFound({ message: 'Not found' });
  
  // Bad request (400)
  return response.badRequest({ message: 'Invalid input' });
  
  // Server error (500)
  return response.error({ message: 'Something went wrong' });
  
  // Custom status and data
  return response.json({ custom: 'data' }, { status: 418 });
}
```

### Error Handling

Igniter.js automatically catches errors and formats them:

```typescript
handler: async ({ request, response }) => {
  // Throw errors - they'll be caught automatically
  if (!request.query.q) {
    throw new Error('Search query is required');
  }
  
  // Or return error responses
  return response.badRequest({ 
    message: 'Invalid query parameters' 
  });
}
```

### Accessing Request Data

```typescript
handler: async ({ request, context, response }) => {
  // Path parameters
  const userId = request.params.id;
  
  // Query parameters (if schema defined)
  const page = request.query.page;
  
  // Request body (if schema defined)
  const userData = request.body;
  
  // Raw headers
  const authHeader = request.headers.get('authorization');
  
  // Cookies
  const sessionId = request.cookies.get('sessionId');
  
  // Raw Request object
  const rawRequest = request.raw;
}
```

<Callout type="success">
  You're now ready to build production-grade APIs with Igniter.js! Check out the [Core Concepts](/docs/builder) to dive deeper.
</Callout>


---

# Advanced Features

> Typed job streams, event subscriptions, telemetry integration, adapter configuration, and production best practices for @igniter-js/jobs.
URL: https://igniterjs.com/docs/jobs/advanced-features

Beyond basic job execution, Igniter.js Jobs provides typed job streams, event subscriptions, telemetry integration, and multiple adapter backends. This page covers the advanced features that make the jobs system production-ready.

## Typed Job Streams

Job streams enable per-job, real-time event streaming — emit typed events during job execution, subscribe to live updates, and read persisted event history.

### Defining Stream Events

Define typed stream events on a job definition:

```typescript
import { z } from 'zod'

const aiQueue = IgniterQueue.create('ai')
  .addJob('generate', {
    input: z.object({ prompt: z.string() }),
    stream: {
      persistence: { enabled: true, maxEvents: 100 },
      events: {
        'text-delta': z.string(),
        'status': z.object({ phase: z.string() }),
        'done': z.object({ chunks: z.number() }),
      },
    },
    handler: async ({ input, job }) => {
      // Emit typed stream events during execution
      await job.stream.emit('status', { phase: 'thinking' })
      await job.stream.emit('text-delta', 'Hello, ')
      await job.stream.emit('text-delta', 'world!')
      await job.stream.emit('done', { chunks: 2 })

      return { ok: true }
    },
  })
  .build()
```

### Stream Configuration

| Option                  | Type                     | Description                    |
| ----------------------- | ------------------------ | ------------------------------ |
| `persistence.enabled`   | `boolean`                | Enable persisted event history |
| `persistence.maxEvents` | `number`                 | Maximum events to retain       |
| `events`                | `Record<string, Schema>` | Typed event schema map         |

### Emitting Events

Inside the handler, use `job.stream.emit(type, data)`:

```typescript
handler: async ({ job }) => {
  await job.stream.emit('status', { phase: 'processing' })
  // TypeScript validates: type must be 'text-delta' | 'status' | 'done'
  // data must match the schema for that event type
}
```

With untyped streams (no `events` schema), you can emit any string type with any data:

```typescript
stream: { persistence: { enabled: false } },
handler: async ({ job }) => {
  await job.stream.emit('custom-event', { any: 'data' })
  // type: string, data: unknown
}
```

### Subscribing to Live Events

```typescript
const job = jobs.ai.generate.get('job_abc123')

const unsubscribe = await job.stream().subscribe((event) => {
  // Fully typed discriminated union:
  if (event.type === 'text-delta') {
    console.log(event.data) // string
  } else if (event.type === 'status') {
    console.log(event.data.phase) // string
  } else if (event.type === 'done') {
    console.log(event.data.chunks) // number
  }
})

// Later: await unsubscribe()
```

### Reading Persisted History

```typescript
const history = await jobs.ai.generate.get('job_abc123').stream().read({
  after: 'event_cursor_123', // Pagination cursor (optional)
  limit: 50,                  // Max events (optional)
})

console.log(history.items)     // Typed event array
console.log(history.hasMore)   // boolean
console.log(history.nextCursor) // string | undefined
```

If `persistence.enabled` is `false`, `read()` returns an empty array.

<Callout type="info" title="Stream Use Cases">
  Job streams are perfect for:

  * **AI/LLM pipelines** — stream token deltas, status updates, and completion events
  * **File processing** — emit progress, chunk info, and final results
  * **Data pipelines** — stream ETL stages, row counts, and validation results
  * **User notifications** — push real-time updates to clients via WebSocket/SSE
</Callout>

***

## Event Subscriptions

Subscribe to job lifecycle events at multiple levels:

### Global Subscription

```typescript
const unsubscribe = await jobs.subscribe((event) => {
  console.log(`[${event.type}]`, event.data)
  // Events include: enqueued, started, completed, failed, etc.
})

// Later
await unsubscribe()
```

### Per-Job Subscription

```typescript
const unsubscribe = await jobs.email.sendWelcome.subscribe((event) => {
  console.log(`sendWelcome: ${event.type}`)
})
```

### Per-Queue Subscription

```typescript
const unsubscribe = await jobs.email.subscribe((event) => {
  console.log(`Email queue event: ${event.type}`)
})
```

### Event Shape

```typescript
interface IgniterJobsEvent {
  type: string           // Event type (e.g., 'igniter.jobs.job.completed')
  data: unknown          // Event payload
  timestamp: Date        // When the event occurred
  scope?: {              // Scope info (if scoped)
    type: string
    id: string | number
    tags?: Record<string, unknown>
  }
}
```

***

## Telemetry Integration

Integrate with `@igniter-js/telemetry` for structured observability:

```typescript
import { IgniterTelemetry } from '@igniter-js/telemetry'
import { IgniterJobsTelemetryEvents } from '@igniter-js/jobs/telemetry'

const telemetry = IgniterTelemetry.create()
  .withService('my-api')
  .withEnvironment('production')
  .addEvents(IgniterJobsTelemetryEvents)
  .build()

const jobs = IgniterJobs.create()
  .withAdapter(IgniterJobsBullMQAdapter.create({ redis }))
  .withService('my-api')
  .withEnvironment('production')
  .withContext(async () => ({ db }))
  .withTelemetry(telemetry)
  .addQueue(emailQueue)
  .build()
```

The jobs runtime automatically emits telemetry events for:

* Job enqueued, started, completed, and failed
* Worker lifecycle changes

***

## Adapters

Igniter.js Jobs ships with three adapters, importable from specific subpaths:

### BullMQ Adapter (Production)

For Redis-backed production deployments:

```typescript
import { IgniterJobsBullMQAdapter } from '@igniter-js/jobs/adapters/node'
import { Redis } from 'ioredis'

const redis = new Redis(process.env.REDIS_URL)

const jobs = IgniterJobs.create()
  .withAdapter(IgniterJobsBullMQAdapter.create({ redis }))
  // ...
  .build()
```

**Requirements:** `@igniter-js/adapter-bullmq`, `bullmq`, `ioredis` (all peer dependencies)

### Bun SQLite Adapter

For standalone deployments without Redis — ideal for single-server apps:

```typescript
import { IgniterJobsBunSQLiteAdapter } from '@igniter-js/jobs/adapters/bun'

const jobs = IgniterJobs.create()
  .withAdapter(IgniterJobsBunSQLiteAdapter.create({
    path: './data/jobs.db',
    durable: true,              // Immediate persistence
    heartbeatInterval: 10_000,  // Worker heartbeat (default: 10000)
    pollTimeout: 0,             // Long-poll timeout (default: 0)
    batchSize: 10,              // Jobs per worker batch (default: 10)
    lockDuration: 30_000,       // Active job lock (default: 30000)
    maxStalledCount: 1,         // Max stalled before fail (default: 1)
  }))
  // ...
  .build()
```

**Requirements:** Bun runtime only

### In-Memory Adapter (Dev/Test)

For development and testing — no external dependencies:

```typescript
import { IgniterJobsMemoryAdapter } from '@igniter-js/jobs/adapters/mock'

const jobs = IgniterJobs.create()
  .withAdapter(IgniterJobsMemoryAdapter.create())
  // ...
  .build()
```

**Requirements:** None — fully self-contained

### Adapter Comparison

| Feature              | BullMQ          | Bun SQLite          | Memory              |
| -------------------- | --------------- | ------------------- | ------------------- |
| Persistence          | Redis           | SQLite file         | In-memory only      |
| Distributed workers  | Yes             | No (single process) | No (single process) |
| Dashboard/monitoring | Bull Board      | Custom              | Custom              |
| Production-ready     | Yes             | Yes (single server) | No (dev/test only)  |
| Setup complexity     | Medium (Redis)  | Low (file)          | None                |
| Import path          | `adapters/node` | `adapters/bun`      | `adapters/mock`     |

***

## Logger Integration

Attach a custom logger to capture internal events:

```typescript
import type { IgniterLogger } from '@igniter-js/jobs'

const logger: IgniterLogger = {
  info: (message, meta) => console.log(`[INFO] ${message}`, meta),
  warn: (message, meta) => console.warn(`[WARN] ${message}`, meta),
  error: (message, meta) => console.error(`[ERROR] ${message}`, meta),
}

const jobs = IgniterJobs.create()
  .withLogger(logger)
  // ...
  .build()
```

***

## Real-World Patterns

### AI Pipeline with Streams

```typescript
const aiQueue = IgniterQueue.create('ai')
  .addJob('generate', {
    input: z.object({ prompt: z.string() }),
    stream: {
      persistence: { enabled: true, maxEvents: 200 },
      events: {
        'token': z.string(),
        'tool-call': z.object({ name: z.string(), args: z.record(z.unknown()) }),
        'done': z.object({ text: z.string(), tokens: z.number() }),
      },
    },
    handler: async ({ input, job, context }) => {
      const stream = await context.llm.stream(input.prompt)

      let text = ''
      let tokens = 0

      for await (const chunk of stream) {
        if (chunk.type === 'token') {
          await job.stream.emit('token', chunk.text)
          text += chunk.text
          tokens++
        } else if (chunk.type === 'tool-call') {
          await job.stream.emit('tool-call', chunk.tool)
        }
      }

      await job.stream.emit('done', { text, tokens })
      return { text, tokens }
    },
  })
  .build()
```

### WebSocket Streaming to Client

```typescript
// Server-side: subscribe to job stream, forward to WebSocket
async function streamJobToClient(ws: WebSocket, jobId: string) {
  const unsubscribe = await jobs.ai.generate
    .get(jobId)
    .stream()
    .subscribe((event) => {
      ws.send(JSON.stringify(event))
    })

  ws.on('close', async () => {
    await unsubscribe()
  })
}
```

### Custom Retry Logic with Hooks

```typescript
const resilientQueue = IgniterQueue.create('api')
  .addJob('sync', {
    input: z.object({ endpoint: z.string().url() }),
    attempts: 5,
    handler: async ({ input }) => {
      const response = await fetch(input.endpoint)
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`)
      }
      return response.json()
    },
    onFailure: async ({ input, job, error, isFinalAttempt }) => {
      if (isFinalAttempt) {
        await alerts.send({
          message: `Sync job failed after ${job.attemptsMade} attempts: ${error.message}`,
        })
      }
    },
  })
  .build()
```

***

## Best Practices

### General

* **Use typed streams** — define event schemas for compile-time safety in AI/streaming pipelines
* **Enable stream persistence** only when you need history — it adds storage overhead
* **Set appropriate adapter** — BullMQ for distributed, Bun SQLite for single-server, Memory for tests
* **Integrate telemetry** — production observability from day one
* **Use scopes** — isolate tenants with `addScope({ required: true })` in multi-tenant apps

### Error Handling

* **Use lifecycle hooks** for logging and alerts, not business logic
* **Set `attempts`** on job definitions — don't rely on infinite retries
* **Monitor failure rates** — use `jobs.search('jobs', { status: 'failed' })` periodically
* **Handle shutdown** — always call `jobs.shutdown()` before process exit

### Performance

* **Match concurrency to workload** — CPU: 2–5, I/O: 10–50, Database: 5–10
* **Use rate limiters** for downstream API calls — prevent 429 errors
* **Clean completed jobs** — prevent Redis memory bloat with `queue.get().clean()`
* **Separate queues by domain** — independent scaling and monitoring

***

## Troubleshooting

### Stream Events Not Persisting

**Problem**: `stream().read()` returns empty when `persistence.enabled` is `true`.

**Solutions**:

* Verify `persistence.enabled: true` is set in the stream config
* Ensure the adapter supports stream persistence (Memory adapter supports it)
* Check `maxEvents` — if exceeded, old events may be evicted

### Telemetry Events Not Emitting

**Problem**: No telemetry events despite calling `withTelemetry()`.

**Solutions**:

* Verify the telemetry instance was built with `IgniterJobsTelemetryEvents`
* Check `service` and `environment` match between telemetry and jobs config
* Ensure the telemetry instance is correctly configured

### Adapter Import Errors

**Problem**: TypeScript can't resolve adapter imports.

**Solutions**:

* BullMQ: `import { IgniterJobsBullMQAdapter } from '@igniter-js/jobs/adapters/node'`
* Bun SQLite: `import { IgniterJobsBunSQLiteAdapter } from '@igniter-js/jobs/adapters/bun'`
* Memory: `import { IgniterJobsMemoryAdapter } from '@igniter-js/jobs/adapters/mock'`

### Scope Required Errors

**Problem**: `JOBS_SCOPE_REQUIRED` error on dispatch.

**Solution**: Use `jobs.scope('type', 'id')` before dispatching, or set `required: false` on the scope definition.

***

## Next Steps

* **[Search & Monitoring](/docs/jobs/search-and-monitoring)** — Find and manage jobs programmatically
* **[Workers](/docs/jobs/workers)** — Configure and scale workers
* **[Scopes](/docs/jobs/scopes)** — Multi-tenant isolation patterns
* **[Telemetry Documentation](/docs/telemetry)** — Full telemetry setup guide


---

# Getting Started

> Set up @igniter-js/jobs and create your first background job in minutes — with BullMQ, Bun SQLite, or in-memory adapters.
URL: https://igniterjs.com/docs/jobs/getting-started

This guide walks you through installing `@igniter-js/jobs`, defining a queue with jobs and cron tasks, creating the jobs runtime, dispatching your first job, and starting a worker. By the end, you'll have a fully working background job system.

## Prerequisites

* **Node.js 18+** or **Bun 1.0+**
* **Redis** (if using the BullMQ adapter) — running locally or via a cloud provider
* Basic familiarity with TypeScript and Zod schemas

<Callout type="info" title="Quick Start Without Redis">
  Use the **in-memory adapter** for development and testing — no external dependencies required.
  Import it from `@igniter-js/jobs/adapters/mock`.
</Callout>

***

## Step 1: Install Dependencies

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/jobs zod
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/jobs zod
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/jobs zod
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/jobs zod
    ```
  </Tab>
</Tabs>

For the BullMQ adapter (production), also install:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/adapter-bullmq bullmq ioredis
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/adapter-bullmq bullmq ioredis
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/adapter-bullmq bullmq ioredis
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/adapter-bullmq bullmq ioredis
    ```
  </Tab>
</Tabs>

***

## Step 2: Set Up Redis (BullMQ)

If you're using the BullMQ adapter, create a Redis client:

```typescript
// src/lib/redis.ts
import { Redis } from 'ioredis'

export const redis = new Redis(
  process.env.REDIS_URL || 'redis://localhost:6379'
)
```

<Callout type="info" title="Skip This For Development">
  For local development, use the in-memory adapter: `IgniterJobsMemoryAdapter.create()` — no Redis needed.
</Callout>

***

## Step 3: Define Your First Queue

Create a queue with jobs and an optional cron task using `IgniterQueue`:

```typescript
// src/jobs/email.queue.ts
import { IgniterQueue } from '@igniter-js/jobs'
import { z } from 'zod'

export const emailQueue = IgniterQueue.create('email')
  .addJob('sendWelcome', {
    input: z.object({
      email: z.string().email(),
      name: z.string(),
    }),
    handler: async ({ input, context }) => {
      console.log(`Sending welcome email to ${input.email}`)
      await context.emailService.sendWelcome(input.email, input.name)
    },
  })
  .addJob('sendPasswordReset', {
    input: z.object({
      email: z.string().email(),
      token: z.string(),
    }),
    handler: async ({ input, context }) => {
      await context.emailService.sendPasswordReset(input.email, input.token)
    },
  })
  .addCron('dailyCleanup', {
    cron: '0 2 * * *', // Every day at 2 AM
    handler: async ({ context }) => {
      await context.emailService.cleanupOldRecords()
    },
  })
  .build()
```

<Callout type="info" title="Type Inference">
  TypeScript infers the input type from your Zod schema. Inside the handler, `input.email` and `input.name` are fully typed — no manual type annotations needed.
</Callout>

***

## Step 4: Create the Jobs Runtime

Use `IgniterJobs.create()` with the fluent builder to configure and build your jobs runtime:

```typescript
// src/services/jobs.ts
import { IgniterJobs } from '@igniter-js/jobs'
import { IgniterJobsBullMQAdapter } from '@igniter-js/jobs/adapters/node'
import { redis } from '@/lib/redis'
import { emailQueue } from '@/jobs/email.queue'

export const jobs = IgniterJobs.create()
  .withAdapter(IgniterJobsBullMQAdapter.create({ redis }))
  .withService('my-api')
  .withEnvironment(process.env.NODE_ENV || 'development')
  .withContext(async () => ({
    emailService: new EmailService(),
  }))
  .addQueue(emailQueue)
  .build()
```

<Callout type="warn" title="Required Builder Methods">
  All four methods — `withAdapter()`, `withService()`, `withEnvironment()`, and `withContext()` — are **required** before calling `build()`. The builder will throw a descriptive error if any are missing.
</Callout>

### Using the In-Memory Adapter

For development and testing, swap the adapter:

```typescript
import { IgniterJobsMemoryAdapter } from '@igniter-js/jobs/adapters/mock'

const jobs = IgniterJobs.create()
  .withAdapter(IgniterJobsMemoryAdapter.create())
  .withService('my-api')
  .withEnvironment('development')
  .withContext(async () => ({ emailService: new EmailService() }))
  .addQueue(emailQueue)
  .build()
```

### Adding Multiple Queues

Register all your queues during the build phase:

```typescript
import { emailQueue } from '@/jobs/email.queue'
import { analyticsQueue } from '@/jobs/analytics.queue'
import { paymentQueue } from '@/jobs/payment.queue'

const jobs = IgniterJobs.create()
  .withAdapter(...)
  .withService('my-api')
  .withEnvironment('production')
  .withContext(async () => ({ db, emailService, paymentService }))
  .addQueue(emailQueue)
  .addQueue(analyticsQueue)
  .addQueue(paymentQueue)
  .build()
```

***

## Step 5: Dispatch a Job

Dispatch jobs from anywhere in your application — API routes, server actions, event handlers:

```typescript
// src/features/users/actions/register.ts
import { jobs } from '@/services/jobs'

export async function registerUser(userData: { email: string; name: string }) {
  // Create the user in your database...
  const user = await db.user.create({ data: userData })

  // Dispatch the welcome email job
  const jobId = await jobs.email.sendWelcome.dispatch({
    input: {
      email: user.email,
      name: user.name,
    },
  })

  console.log(`Welcome email job dispatched: ${jobId}`)
  return user
}
```

### Dispatch with Options

Control priority, delay, attempts, and more:

```typescript
await jobs.email.sendWelcome.dispatch({
  input: { email: 'user@example.com', name: 'Alice' },
  priority: 10,           // Higher priority jobs processed first
  delay: 5000,            // Delay execution by 5 seconds
  attempts: 5,            // Retry up to 5 times on failure
  jobId: 'custom-job-id', // Custom job identifier
  metadata: {             // Custom metadata for search/filtering
    source: 'signup-flow',
  },
})
```

***

## Step 6: Start a Worker

Workers process jobs from queues. Create one with the fluent worker builder:

```typescript
// src/workers/start.ts
import { jobs } from '@/services/jobs'

const emailWorker = await jobs.worker.create()
  .addQueue('email')
  .withConcurrency(5)
  .onActive(({ job }) => {
    console.log(`Processing ${job.name} (${job.id})`)
  })
  .onSuccess(({ job, result }) => {
    console.log(`Completed ${job.name}:`, result)
  })
  .onFailure(({ job, error }) => {
    console.error(`Failed ${job.name}:`, error.message)
  })
  .start()

console.log('Worker started:', emailWorker.id)
```

### Auto-Start Workers

Alternatively, configure workers to start automatically when `build()` is called:

```typescript
const jobs = IgniterJobs.create()
  .withAdapter(IgniterJobsBullMQAdapter.create({ redis }))
  .withService('my-api')
  .withEnvironment('production')
  .withContext(async () => ({ emailService }))
  .addQueue(emailQueue)
  .withAutoStartWorker({
    queues: ['email'],
    concurrency: 5,
  })
  .build()
// Worker starts automatically — no manual start() call needed
```

***

## Step 7: Verify It Works

<Steps>
  <Step>
    **Start your application**

    ```bash
    npm run dev
    ```
  </Step>

  <Step>
    **Dispatch a test job** — trigger the endpoint or call it programmatically:

    ```typescript
    const jobId = await jobs.email.sendWelcome.dispatch({
      input: { email: 'test@example.com', name: 'Test User' },
    })
    console.log('Dispatched:', jobId)
    ```
  </Step>

  <Step>
    **Check the logs** — with a worker running, you should see:

    ```
    Processing sendWelcome (job_abc123)
    Sending welcome email to test@example.com
    Completed sendWelcome: { sent: true }
    ```
  </Step>
</Steps>

<Callout type="success" title="Success!">
  Your jobs system is working. You can now dispatch background jobs from anywhere in your application.
</Callout>

***

## Next Steps

Now that you have a working job setup, explore:

* **[Job Definitions](/docs/jobs/job-definitions)** — Configure hooks, retry options, and output schemas
* **[Scheduling](/docs/jobs/scheduling)** — Dispatch with delays, at specific times, or on cron schedules
* **[Workers](/docs/jobs/workers)** — Fine-tune concurrency, rate limiters, and lifecycle handlers
* **[Scopes](/docs/jobs/scopes)** — Multi-tenant isolation with scoped instances
* **[Advanced Features](/docs/jobs/advanced-features)** — Job streams, events, and telemetry

***

## Troubleshooting

### Jobs Not Processing

**Problem**: Jobs are dispatched but never execute.

**Solutions**:

* Verify a worker is running for the queue — check logs for `"Worker started"`
* Ensure the worker's `addQueue('email')` matches the queue name exactly
* Check Redis connectivity with `redis-cli ping`

### Redis Connection Errors

**Problem**: `ECONNREFUSED` when using the BullMQ adapter.

**Solutions**:

* Ensure Redis is running: `redis-cli ping` should return `PONG`
* Verify your `REDIS_URL` environment variable
* For local development, switch to the in-memory adapter

### TypeScript Errors

**Problem**: TypeScript can't find adapter imports.

**Solutions**:

* BullMQ adapter: use `@igniter-js/jobs/adapters/node`
* Memory adapter: use `@igniter-js/jobs/adapters/mock`
* Bun SQLite adapter: use `@igniter-js/jobs/adapters/bun`

### Builder Validation Errors

**Problem**: `build()` throws `JOBS_ADAPTER_REQUIRED` or similar.

**Solution**: Ensure all four required methods are called:
`withAdapter()` → `withService()` → `withEnvironment()` → `withContext()` → `build()`


---

# Jobs

> Type-safe background job processing with fluent builders, cron scheduling, worker management, job streams, and observability — powered by BullMQ, Bun SQLite, or in-memory adapters.
URL: https://igniterjs.com/docs/jobs

The **Jobs** package in Igniter.js brings type-safe background job processing to your application. Built on a fluent builder API with full TypeScript inference, it supports immediate dispatch, delayed scheduling, cron-based recurrence, multi-queue workers, scoped multi-tenancy, typed job streams, and built-in observability.

## Key Features

* **Type-Safe Builders** — Fluent API with full type inference for queues, jobs, input schemas, and results
* **Adapter-Agnostic** — BullMQ, Bun SQLite, and in-memory adapters — same API, any backend
* **Cron & Delayed Scheduling** — Dispatch immediately, with a delay, at a specific time, or on a cron schedule
* **Worker Management** — Create workers with per-queue concurrency control, rate limiters, and lifecycle hooks
* **Job Lifecycle Hooks** — `onStart`, `onSuccess`, `onFailure`, and `onProgress` hooks on every job
* **Typed Job Streams** — Emit, subscribe, and read typed per-job event streams (great for LLM-chunking, progress, logs)
* **Scope-Based Multi-Tenancy** — Isolate jobs by organization, workspace, or environment with `jobs.scope()`
* **Queue Management** — Pause, resume, drain, clean, obliterate, and inspect queues programmatically
* **Observability** — Built-in events, subscribe API, and optional telemetry integration

## Architecture Overview

Igniter.js Jobs follow an **adapter-based architecture**. The core runtime defines the fluent builder interface and runtime types. Concrete adapters provide the actual queue processing backend.

```
┌──────────────────────────────────────────────┐
│           @igniter-js/jobs                   │
│   (Fluent Builders + Runtime + Types)        │
└──────────────────┬───────────────────────────┘
                   │
     ┌─────────────┼─────────────┐
     ▼             ▼             ▼
┌─────────┐  ┌──────────┐  ┌──────────┐
│ BullMQ  │  │Bun SQLite│  │  Memory  │
│ Adapter │  │  Adapter │  │  Adapter │
└────┬────┘  └────┬─────┘  └──────────┘
     │            │
     ▼            ▼
  ┌──────┐   ┌─────────┐
  │ Redis│   │ SQLite  │
  └──────┘   └─────────┘
```

## Quick Example

Here's a minimal example showing how to set up and use jobs:

```typescript
import { IgniterJobs, IgniterQueue } from '@igniter-js/jobs'
import { IgniterJobsMemoryAdapter } from '@igniter-js/jobs/adapters/mock'
import { z } from 'zod'

// 1. Define a queue with jobs
const emailQueue = IgniterQueue.create('email')
  .addJob('sendWelcome', {
    input: z.object({ email: z.string().email(), name: z.string() }),
    handler: async ({ input }) => {
      console.log(`Sending welcome email to ${input.email}`)
      return { sent: true }
    },
  })
  .addCron('dailyDigest', {
    cron: '0 9 * * *',
    handler: async ({ context }) => {
      await context.emailService.sendDailyDigest()
    },
  })
  .build()

// 2. Create the jobs runtime
const jobs = IgniterJobs.create()
  .withAdapter(IgniterJobsMemoryAdapter.create())
  .withService('my-api')
  .withEnvironment('production')
  .withContext(async () => ({
    emailService: new EmailService(),
  }))
  .addQueue(emailQueue)
  .build()

// 3. Dispatch a job
await jobs.email.sendWelcome.dispatch({
  input: { email: 'user@example.com', name: 'Alice' },
})

// 4. Start a worker to process jobs
await jobs.worker.create()
  .addQueue('email')
  .withConcurrency(5)
  .start()
```

<Callout type="info" title="What's Next?">
  Ready to dive in? Start with the [Getting Started](/docs/jobs/getting-started) guide to set up your first job, or explore [Job Definitions](/docs/jobs/job-definitions) to understand how queues and jobs are structured.
</Callout>

## Documentation Structure

This documentation is organized into logical sections:

* **Getting Started** — Install and create your first job in minutes
* **Job Definitions** — Build queues, register jobs and crons, configure hooks
* **Scheduling** — Dispatch immediately, with delays, at specific times, or on cron schedules
* **Workers** — Create, configure, and manage workers with concurrency and rate limiting
* **Scopes** — Multi-tenant isolation with scoped job instances
* **Search & Monitoring** — Find, filter, and manage jobs and queues
* **Advanced Features** — Job streams, event subscriptions, telemetry, and adapter details

***

## Related Resources

* **[Store Documentation](/docs/store)** — The Redis adapter used by the jobs system
* **[Context](/docs/context)** — How application context works with jobs
* **[Telemetry](/docs/telemetry)** — Telemetry integration for observability
* **[GitHub Repository](https://github.com/felipebarcelospro/igniter-js)** — Source code and examples


---

# Job Definitions

> Build type-safe queues and jobs with Zod schemas, lifecycle hooks, retry configuration, and output validation.
URL: https://igniterjs.com/docs/jobs/job-definitions

Job definitions are built using the `IgniterQueue` builder. You create queues, register jobs (with handlers, schemas, and hooks), and optionally add cron tasks — all with full TypeScript type inference.

## Creating a Queue

Use `IgniterQueue.create(name)` to start a new queue builder:

```typescript
import { IgniterQueue } from '@igniter-js/jobs'

const queue = IgniterQueue.create('email')
```

The queue name is used as the namespace for dispatching jobs: `jobs.email.sendWelcome.dispatch(...)`.

***

## Adding Jobs

Call `.addJob(name, definition)` on the queue builder to register a job:

```typescript
import { z } from 'zod'

const emailQueue = IgniterQueue.create('email')
  .addJob('sendWelcome', {
    input: z.object({
      email: z.string().email(),
      name: z.string(),
    }),
    handler: async ({ input, context, job }) => {
      console.log(`Sending welcome email to ${input.email}`)
      await context.mailer.sendWelcome(input.email, input.name)
      return { sent: true, timestamp: new Date() }
    },
  })
  .build()
```

### Job Definition Properties

| Property     | Type                                   | Required | Description                                           |
| ------------ | -------------------------------------- | -------- | ----------------------------------------------------- |
| `handler`    | `(ctx) => Promise<TResult> \| TResult` | **Yes**  | The function that executes when the job runs          |
| `input`      | `IgniterJobsSchema`                    | No       | Schema for input validation (Zod, Standard Schema v1) |
| `output`     | `IgniterJobsSchema`                    | No       | Schema for output validation                          |
| `onStart`    | `(ctx) => void \| Promise<void>`       | No       | Called when job execution begins                      |
| `onSuccess`  | `(ctx) => void \| Promise<void>`       | No       | Called when job completes successfully                |
| `onFailure`  | `(ctx) => void \| Promise<void>`       | No       | Called when job fails                                 |
| `onProgress` | `(ctx) => void \| Promise<void>`       | No       | Called when the job reports progress                  |
| `stream`     | `IgniterJobsJobStreamDefinition`       | No       | Typed per-job event stream configuration              |
| `queue`      | `string`                               | No       | Optional child queue override (adapter-dependent)     |

Plus all [dispatch options](#dispatch-options) can be set as defaults on the job definition.

***

## The Handler Context

The handler receives an execution context with everything it needs:

```typescript
interface IgniterJobsExecutionContext<TContext, TInput, TStreamEvents> {
  input: InferInput<TInput>        // Validated input (fully typed)
  context: TContext                // Your application context
  job: {
    id: string                     // Unique job identifier
    name: string                   // Job name (e.g., 'sendWelcome')
    queue: string                  // Queue name
    attemptsMade: number           // How many times this job has run
    createdAt?: Date               // When the job was created
    metadata?: Record<string, unknown>
    updateProgress?: (progress: number, message?: string) => Promise<void>
    stream: IgniterJobsExecutionStreamEmitter  // Typed stream emitter
  }
  scope?: IgniterJobsScopeEntry    // Scope info if dispatched from a scoped instance
}
```

### Context Type Inference

The context type is inferred from `withContext()` on the main builder — no explicit generics needed:

```typescript
const jobs = IgniterJobs.create()
  .withContext(async () => ({
    db: new PrismaClient(),
    mailer: new Mailer(),
  }))
  // TContext = { db: PrismaClient; mailer: Mailer }
  .addQueue(emailQueue)
  .build()

// Inside the handler:
// context.db   → PrismaClient (fully typed)
// context.mailer → Mailer (fully typed)
```

***

## Input Validation

Jobs automatically validate their input against the provided schema. Invalid input causes the job to fail before the handler executes:

```typescript
const processOrderQueue = IgniterQueue.create('orders')
  .addJob('process', {
    input: z.object({
      orderId: z.string().uuid(),
      amount: z.number().positive(),
      currency: z.enum(['USD', 'EUR', 'GBP']),
    }),
    handler: async ({ input }) => {
      // input.orderId is typed as string
      // input.amount is typed as number (> 0)
      // input.currency is typed as 'USD' | 'EUR' | 'GBP'
      console.log(`Processing order ${input.orderId}`)
    },
  })
  .build()

// ✅ Valid — job executes
await jobs.orders.process.dispatch({
  input: { orderId: '123e4567-e89b-12d3-a456-426614174000', amount: 99.99, currency: 'USD' },
})

// ❌ Invalid — throws JOBS_INPUT_VALIDATION_FAILED
await jobs.orders.process.dispatch({
  input: { orderId: 'not-a-uuid', amount: -10, currency: 'JPY' },
})
```

### Supported Schema Libraries

The `input` and `output` fields support:

* **Zod** schemas (with `_input`/`_output` and `parse`/`safeParse`)
* **Standard Schema v1** compatible schemas
* **Any object** with `parse()` and optional `safeParse()`

<Callout type="info" title="Output Validation">
  The `output` schema validates the handler's return value. If validation fails, the job is marked as failed with a `JOBS_OUTPUT_VALIDATION_FAILED` error.
</Callout>

***

## Lifecycle Hooks

React to job lifecycle events without modifying the handler:

```typescript
const trackedJob = IgniterQueue.create('analytics')
  .addJob('track', {
    input: z.object({ event: z.string(), userId: z.string() }),
    handler: async ({ input, context }) => {
      await context.analytics.track(input.event, input.userId)
      return { tracked: true }
    },

    onStart: async ({ input, job }) => {
      console.log(`Job ${job.name} (${job.id}) started`)
    },

    onProgress: async ({ job, progress, message }) => {
      console.log(`Job ${job.id} progress: ${progress}% — ${message}`)
    },

    onSuccess: async ({ input, job, result, duration }) => {
      console.log(`Job ${job.name} completed in ${duration}ms`)
      await context.metrics.record('job.success', { duration })
    },

    onFailure: async ({ input, job, error, isFinalAttempt }) => {
      console.error(`Job ${job.name} failed:`, error.message)
      if (isFinalAttempt) {
        await context.alerts.send({
          type: 'critical',
          message: `Job ${job.name} failed after all retries`,
        })
      }
    },
  })
  .build()
```

### Hook Context

Each hook receives a typed context:

| Hook         | Additional Properties                     |
| ------------ | ----------------------------------------- |
| `onStart`    | `startedAt`                               |
| `onProgress` | `progress: number`, `message?: string`    |
| `onSuccess`  | `result: TResult`, `duration?: number`    |
| `onFailure`  | `error: Error`, `isFinalAttempt: boolean` |

<Callout type="info" title="Hook Execution">
  Hooks execute asynchronously and errors in hooks **do not fail the job**. Use hooks for logging, metrics, and notifications — not critical business logic.
</Callout>

***

## Dispatch Options

All dispatch options can be set as **defaults** on the job definition or **overridden** at dispatch time:

```typescript
const queue = IgniterQueue.create('email')
  .addJob('sendWelcome', {
    // Job defaults (applied to every dispatch)
    attempts: 3,
    priority: 5,
    removeOnComplete: 100,
    removeOnFail: 50,

    handler: async ({ input }) => {
      await sendEmail(input.email)
    },
  })
  .build()

// Override defaults at dispatch time
await jobs.email.sendWelcome.dispatch({
  input: { email: 'urgent@example.com', name: 'VIP' },
  priority: 10,     // Override default priority
  attempts: 5,      // Override default attempts
  delay: 0,         // Send immediately
})
```

### Available Dispatch Options

| Option             | Type                      | Default        | Description                            |
| ------------------ | ------------------------- | -------------- | -------------------------------------- |
| `input`            | `TInput`                  | **Required**   | Validated input payload                |
| `jobId`            | `string`                  | Auto-generated | Custom job identifier                  |
| `priority`         | `number`                  | —              | Higher = processed first               |
| `delay`            | `number`                  | 0              | Delay in milliseconds before execution |
| `attempts`         | `number`                  | —              | Maximum execution attempts             |
| `removeOnComplete` | `boolean \| number`       | —              | Auto-remove completed jobs (or keep N) |
| `removeOnFail`     | `boolean \| number`       | —              | Auto-remove failed jobs (or keep N)    |
| `metadata`         | `Record<string, unknown>` | —              | Custom metadata for search/filtering   |
| `limiter`          | `{ max, duration }`       | —              | Per-job rate limiter                   |
| `scope`            | `IgniterJobsScopeEntry`   | —              | Scope entry for multi-tenant isolation |

***

## Queue-Level Defaults

Apply defaults to all jobs in a queue using `.withQueueDefaults()` on the main builder:

```typescript
const jobs = IgniterJobs.create()
  .withAdapter(...)
  .withService('my-api')
  .withEnvironment('production')
  .withContext(async () => ({ db }))
  .withQueueDefaults({
    attempts: 3,
    removeOnComplete: 200,
    removeOnFail: 100,
  })
  .addQueue(emailQueue)
  .addQueue(analyticsQueue)
  .build()
// All jobs inherit these defaults unless overridden
```

***

## Multiple Queues Pattern

Organize jobs into separate queues by domain:

```typescript
// src/jobs/email.queue.ts
export const emailQueue = IgniterQueue.create('email')
  .addJob('sendWelcome', { /* ... */ })
  .addJob('sendPasswordReset', { /* ... */ })
  .build()

// src/jobs/payment.queue.ts
export const paymentQueue = IgniterQueue.create('payment')
  .addJob('processPayment', { /* ... */ })
  .addJob('refundPayment', { /* ... */ })
  .build()

// src/jobs/analytics.queue.ts
export const analyticsQueue = IgniterQueue.create('analytics')
  .addJob('trackEvent', { /* ... */ })
  .addJob('generateReport', { /* ... */ })
  .build()

// src/services/jobs.ts
const jobs = IgniterJobs.create()
  .withAdapter(...)
  .withService('my-api')
  .withEnvironment('production')
  .withContext(async () => ({ db, mailer, paymentService }))
  .addQueue(emailQueue)
  .addQueue(paymentQueue)
  .addQueue(analyticsQueue)
  .build()

// Dispatch from any queue
await jobs.email.sendWelcome.dispatch({ ... })
await jobs.payment.processPayment.dispatch({ ... })
await jobs.analytics.trackEvent.dispatch({ ... })
```

***

## Real-World Examples

### Email Notification Job with Retry

```typescript
const emailQueue = IgniterQueue.create('email')
  .addJob('sendNotification', {
    input: z.object({
      to: z.string().email(),
      subject: z.string().min(1),
      body: z.string(),
    }),
    attempts: 3,
    handler: async ({ input, context }) => {
      const result = await context.mailer.send(input)
      if (!result.success) {
        throw new Error(`Mail send failed: ${result.error}`)
      }
      return { messageId: result.id }
    },
    onFailure: async ({ job, error, isFinalAttempt }) => {
      if (isFinalAttempt) {
        await context.notifications.sendSlack({
          text: `Failed to send email to ${input.to}: ${error.message}`,
        })
      }
    },
  })
  .build()
```

### Order Processing with Database Transaction

```typescript
const orderQueue = IgniterQueue.create('orders')
  .addJob('process', {
    input: z.object({
      orderId: z.string(),
      items: z.array(z.object({
        productId: z.string(),
        quantity: z.number().positive(),
      })),
    }),
    handler: async ({ input, context }) => {
      return await context.db.$transaction(async (tx) => {
        const order = await tx.order.update({
          where: { id: input.orderId },
          data: { status: 'PROCESSING' },
        })

        for (const item of input.items) {
          await tx.inventory.decrement({
            where: { productId: item.productId },
            data: { quantity: item.quantity },
          })
        }

        await tx.order.update({
          where: { id: input.orderId },
          data: { status: 'COMPLETED' },
        })

        return { orderId: order.id, processed: true }
      })
    },
  })
  .build()
```

### File Processing with Progress

```typescript
const mediaQueue = IgniterQueue.create('media')
  .addJob('processImage', {
    input: z.object({
      fileId: z.string(),
      operations: z.array(z.enum(['resize', 'optimize', 'watermark'])),
    }),
    handler: async ({ input, job, context }) => {
      const file = await context.storage.get(input.fileId)

      for (let i = 0; i < input.operations.length; i++) {
        const op = input.operations[i]
        await context.imageProcessor[op](file)
        await job.updateProgress(
          Math.round(((i + 1) / input.operations.length) * 100),
          `Completed ${op}`
        )
      }

      return { processed: true, fileId: input.fileId }
    },
  })
  .build()
```

***

## Best Practices

* **Use descriptive queue names** — queue names appear in logs, metrics, and monitoring tools
* **Validate input strictly** — use Zod's full validation power (`.email()`, `.url()`, `.min()`, `.max()`)
* **Keep handlers focused** — each job should do one thing well; compose jobs for complex workflows
* **Use context for dependencies** — access services through context, not global state
* **Set reasonable attempts** — 3 retries is a good starting point; adjust based on failure patterns
* **Use hooks for observability** — log, track metrics, and alert from hooks, not inside handlers
* **Separate queues by domain** — email, payment, analytics queues let you scale and monitor independently

***

## Next Steps

* **[Scheduling](/docs/jobs/scheduling)** — Dispatch with delays, at specific times, or on cron schedules
* **[Workers](/docs/jobs/workers)** — Configure workers to process your queues
* **[Advanced Features](/docs/jobs/advanced-features)** — Job streams, events, and telemetry


---

# Scheduling

> Schedule jobs for immediate dispatch, delayed execution, specific times, or recurring cron patterns — with timezone support, business hours, and advanced scheduling options.
URL: https://igniterjs.com/docs/jobs/scheduling

Igniter.js Jobs supports a spectrum of scheduling: immediate dispatch, delayed execution, scheduled at-a-specific-time, and recurring cron-based patterns. Every scheduling option is type-safe and validated at runtime.

## Immediate Dispatch

The simplest form — fire and forget:

```typescript
const jobId = await jobs.email.sendWelcome.dispatch({
  input: { email: 'user@example.com', name: 'Alice' },
})
```

Returns a `string` — the job ID for tracking.

***

## Delayed Dispatch

Add a delay (in milliseconds) to run the job after a waiting period:

```typescript
// Run after 30 seconds
await jobs.email.sendReminder.dispatch({
  input: { userId: '123' },
  delay: 30_000,
})

// Run after 1 hour
await jobs.analytics.generateReport.dispatch({
  input: { reportType: 'daily' },
  delay: 3_600_000,
})
```

***

## Schedule at a Specific Time

Use `.schedule()` with the `at` option to run at an exact date/time:

```typescript
await jobs.email.sendCampaign.schedule({
  input: { campaignId: 'summer-sale' },
  at: new Date('2025-07-01T10:00:00Z'), // July 1st, 10 AM UTC
})
```

<Callout type="warn" title="Future Dates Only">
  The `at` option must be a date in the future. Scheduling for a past date will throw an error.
</Callout>

***

## Repeating Jobs

Use `.schedule()` for one-off jobs that repeat. Define the repeat pattern inline:

### Repeat Every N Milliseconds

```typescript
await jobs.analytics.healthCheck.schedule({
  input: {},
  every: 60_000, // Every 60 seconds
})
```

### Cron-Based Recurrence

```typescript
await jobs.maintenance.cleanup.schedule({
  input: {},
  cron: '0 2 * * *',  // Every day at 2 AM
  tz: 'America/New_York',
})
```

### Limited Recurrence

```typescript
await jobs.notifications.sendReminder.schedule({
  input: { campaignId: 'onboarding' },
  cron: '0 9 * * *',    // Every day at 9 AM
  maxExecutions: 7,      // Run 7 times total (one week)
  tz: 'America/New_York',
})
```

<Callout type="info" title="schedule() vs addCron()">
  Use `.schedule()` for ad-hoc recurring jobs dispatched from application code. Use `.addCron()` on the queue builder for **persistent** cron jobs that are part of your queue definition and always registered with the adapter.
</Callout>

***

## Scheduling Options

All scheduling options available on `.schedule()`:

| Option              | Type                        | Description                                                  |
| ------------------- | --------------------------- | ------------------------------------------------------------ |
| `at`                | `Date`                      | Run at a specific date/time (one-time)                       |
| `delay`             | `number`                    | Delay in milliseconds before execution                       |
| `cron`              | `string`                    | Cron expression for repeating jobs                           |
| `every`             | `number`                    | Repeat every N milliseconds (mutually exclusive with `cron`) |
| `maxExecutions`     | `number`                    | Maximum number of executions for repeating jobs              |
| `tz`                | `string`                    | Timezone for cron expression (e.g., `'America/New_York'`)    |
| `skipWeekends`      | `boolean`                   | Skip execution on Saturday and Sunday                        |
| `onlyBusinessHours` | `boolean`                   | Only execute during business hours                           |
| `businessHours`     | `{ start, end, timezone? }` | Business hour range (24h format)                             |
| `onlyWeekdays`      | `number[]`                  | Only execute on these weekdays (0=Sunday..6=Saturday)        |
| `skipDates`         | `Array<string \| Date>`     | Dates to skip execution                                      |
| `startDate`         | `Date`                      | When to start the schedule                                   |
| `endDate`           | `Date`                      | When to end the schedule                                     |

***

## Business Hours Scheduling

Run jobs only during business hours:

```typescript
await jobs.notifications.sendAlert.schedule({
  input: { userId: '123', message: 'Reminder' },
  cron: '0 * * * *',           // Every hour
  onlyBusinessHours: true,
  businessHours: {
    start: 9,                   // 9 AM
    end: 17,                    // 5 PM
    timezone: 'America/New_York',
  },
})
```

### Skip Weekends

```typescript
await jobs.reports.generateDaily.schedule({
  input: {},
  cron: '0 9 * * *',     // Every day at 9 AM
  skipWeekends: true,      // Skip Saturday and Sunday
})
```

### Specific Weekdays

```typescript
await jobs.reports.weeklySummary.schedule({
  input: {},
  cron: '0 9 * * *',           // Daily at 9 AM
  onlyWeekdays: [1, 3, 5],     // Monday, Wednesday, Friday only
})
```

### Skip Specific Dates

```typescript
await jobs.marketing.sendCampaign.schedule({
  input: { campaignId: 'holiday-sale' },
  cron: '0 10 * * *',
  skipDates: [
    '2025-12-25',  // Christmas
    new Date('2025-01-01'), // New Year's
  ],
})
```

***

## Cron Jobs on Queue Definitions

For persistent, always-registered cron jobs, use `.addCron()` on the queue builder:

```typescript
const maintenanceQueue = IgniterQueue.create('maintenance')
  .addJob('cleanup', {
    handler: async ({ context }) => {
      await context.db.cleanup()
    },
  })
  .addCron('dailyBackup', {
    cron: '0 3 * * *',            // Every day at 3 AM
    tz: 'America/New_York',
    handler: async ({ context }) => {
      await context.db.backup()
      return { backedUp: true }
    },
  })
  .addCron('weeklyReport', {
    cron: '0 9 * * 1',            // Every Monday at 9 AM
    onlyWeekdays: [1],
    handler: async ({ context }) => {
      const report = await context.reports.generateWeekly()
      await context.mailer.send(report)
    },
  })
  .build()
```

### Cron Definition Properties

| Property            | Type                        | Required | Description                     |
| ------------------- | --------------------------- | -------- | ------------------------------- |
| `cron`              | `string`                    | **Yes**  | Cron expression (5 or 6 fields) |
| `handler`           | `(ctx) => Promise<TResult>` | **Yes**  | Handler function                |
| `tz`                | `string`                    | No       | Timezone for cron evaluation    |
| `maxExecutions`     | `number`                    | No       | Maximum number of executions    |
| `skipWeekends`      | `boolean`                   | No       | Skip Saturday and Sunday        |
| `onlyBusinessHours` | `boolean`                   | No       | Only during business hours      |
| `businessHours`     | `{ start, end, timezone? }` | No       | Business hour range             |
| `onlyWeekdays`      | `number[]`                  | No       | Restricted weekdays (0-6)       |
| `skipDates`         | `Array<string \| Date>`     | No       | Dates to skip                   |
| `startDate`         | `Date`                      | No       | Schedule start date             |
| `endDate`           | `Date`                      | No       | Schedule end date               |

<Callout type="info" title="Cron Handler Context">
  Unlike job handlers, cron handlers receive `context` without `input` — there's no input payload for scheduled cron tasks.
</Callout>

***

## Cron Expression Guide

Cron expressions follow the format: `minute hour day month weekday [year]`

```
┌───────────── minute (0–59)
│ ┌───────────── hour (0–23)
│ │ ┌───────────── day of month (1–31)
│ │ │ ┌───────────── month (1–12)
│ │ │ │ ┌───────────── day of week (0–6) (Sunday to Saturday)
│ │ │ │ │
* * * * *
```

**Common patterns:**

| Expression        | Meaning                              |
| ----------------- | ------------------------------------ |
| `0 * * * *`       | Every hour at minute 0               |
| `0 9 * * *`       | Every day at 9 AM                    |
| `0 0 * * 0`       | Every Sunday at midnight             |
| `0 0 1 * *`       | First day of every month             |
| `*/5 * * * *`     | Every 5 minutes                      |
| `0 9-17 * * 1-5`  | Every hour, 9 AM–5 PM, Monday–Friday |
| `0 0 1,15 * *`    | 1st and 15th of every month          |
| `0 8,12,18 * * *` | Daily at 8 AM, 12 PM, and 6 PM       |

***

## Real-World Examples

### Daily Report at End of Business Day

```typescript
await jobs.reports.generateDaily.schedule({
  input: {},
  cron: '0 23 * * *',       // 11 PM daily
  tz: 'America/New_York',
})
```

### Hourly Health Check During Business Hours

```typescript
await jobs.monitoring.healthCheck.schedule({
  input: {},
  cron: '0 * * * *',          // Every hour
  onlyBusinessHours: true,
  businessHours: { start: 9, end: 17 },
  tz: 'America/New_York',
})
```

### One-Time Scheduled Reminder

```typescript
const reminderDate = new Date()
reminderDate.setHours(reminderDate.getHours() + 24)

await jobs.email.sendReminder.schedule({
  input: { userId: '123', type: 'trial-expiring' },
  at: reminderDate,
})
```

### Weekly Cleanup with Skip Dates

```typescript
await jobs.maintenance.weeklyCleanup.schedule({
  input: {},
  cron: '0 3 * * 0',           // Sunday at 3 AM
  skipDates: ['2025-12-28'],    // Skip holiday week
  tz: 'UTC',
})
```

***

## Best Practices

* **Always specify timezones** for cron schedules — server timezones are unpredictable
* **Set maxExecutions** for one-off recurring jobs to prevent infinite loops
* **Use `skipIfRunning` patterns** — consider job deduplication for long-running cron jobs
* **Validate cron expressions** — test with an online validator before deploying
* **Separate ad-hoc from persistent** — use `.schedule()` for dynamic, `.addCron()` for infrastructure

***

## Next Steps

* **[Workers](/docs/jobs/workers)** — Configure workers to process your scheduled jobs
* **[Scopes](/docs/jobs/scopes)** — Multi-tenant isolation for scheduled jobs
* **[Search & Monitoring](/docs/jobs/search-and-monitoring)** — Track and monitor job execution


---

# Scopes

> Isolate jobs by organization, workspace, or environment with typed scopes — built-in multi-tenancy for background job processing.
URL: https://igniterjs.com/docs/jobs/scopes

Scopes provide multi-tenant isolation for your background jobs. A scope is a typed label that's attached to every job dispatched from a scoped instance, enabling you to partition jobs by organization, workspace, environment, or any other dimension — all within the same jobs runtime.

## Defining a Scope

Define a scope on the main builder using `addScope()`:

```typescript
const jobs = IgniterJobs.create()
  .withAdapter(IgniterJobsBullMQAdapter.create({ redis }))
  .withService('my-api')
  .withEnvironment('production')
  .withContext(async () => ({ db }))
  .addScope('organization', {
    required: true,                       // Scope is mandatory for dispatch
    description: 'Customer organization', // Human-friendly description
  })
  .addQueue(emailQueue)
  .addQueue(analyticsQueue)
  .build()
```

### Scope Options

| Option        | Type      | Default | Description                                            |
| ------------- | --------- | ------- | ------------------------------------------------------ |
| `required`    | `boolean` | `false` | If `true`, dispatching without a scope throws an error |
| `description` | `string`  | —       | Human-friendly description for documentation           |

***

## Creating a Scoped Instance

Use `jobs.scope(type, id, tags?)` to create a scoped instance:

```typescript
// Create a scoped instance for organization "org_123"
const orgJobs = jobs.scope('organization', 'org_123')

// All jobs dispatched from orgJobs carry the scope metadata
await orgJobs.email.sendWelcome.dispatch({
  input: { email: 'user@example.com', name: 'Alice' },
})

// Scoped instances have the same typed queue accessors
await orgJobs.analytics.trackEvent.dispatch({
  input: { event: 'signup', userId: '456' },
})
```

### Optional Tags

Attach additional metadata to the scope:

```typescript
const proOrgJobs = jobs.scope('organization', 'org_456', {
  plan: 'pro',
  region: 'us-east',
})

// Tags are included in job metadata for search/filtering
await proOrgJobs.email.sendWelcome.dispatch({
  input: { email: 'vip@example.com', name: 'VIP' },
})
```

***

## Required Scopes

When `required: true` is set on the scope definition, dispatching from the unscoped instance throws an error:

```typescript
const jobs = IgniterJobs.create()
  .addScope('organization', { required: true })
  // ...
  .build()

// ❌ Throws: JOBS_SCOPE_REQUIRED
await jobs.email.sendWelcome.dispatch({
  input: { email: 'user@example.com' },
})

// ✅ Works — dispatched from a scoped instance
const orgJobs = jobs.scope('organization', 'org_123')
await orgJobs.email.sendWelcome.dispatch({
  input: { email: 'user@example.com' },
})
```

***

## Multi-Tenant Patterns

### Per-Organization Isolation

```typescript
// Define the jobs runtime once
const jobs = IgniterJobs.create()
  .withAdapter(...)
  .withService('saas-api')
  .withEnvironment('production')
  .withContext(async () => ({ db }))
  .addScope('organization', { required: true })
  .addQueue(emailQueue)
  .addQueue(paymentQueue)
  .build()

// Create scoped instances on-demand per request
async function handleRequest(orgId: string, userId: string) {
  const orgJobs = jobs.scope('organization', orgId)

  await orgJobs.email.sendWelcome.dispatch({
    input: { email: 'user@example.com', name: 'New User' },
  })
}
```

### Environment-Based Partitioning

```typescript
const jobs = IgniterJobs.create()
  .addScope('environment', { required: false })
  // ...
  .build()

const devJobs = jobs.scope('environment', 'development')
const prodJobs = jobs.scope('environment', 'production')

// Jobs are tagged with their environment
await devJobs.email.sendWelcome.dispatch({ ... })
await prodJobs.email.sendWelcome.dispatch({ ... })
```

### Scoped Workers

Workers process all jobs regardless of scope — scoping affects dispatch metadata, not worker processing:

```typescript
// A single worker processes jobs from all scopes
const worker = await jobs.worker.create()
  .addQueue('email')
  .withConcurrency(5)
  .onActive(({ job }) => {
    // job.scope contains the scope info if the job was dispatched from a scoped instance
    if (job.scope) {
      console.log(`Processing scoped job: ${job.scope.type}=${job.scope.id}`)
    }
  })
  .start()
```

### Context-Aware Scoping

Dynamically resolve the scope from application context:

```typescript
// Express middleware pattern
function withJobsScope(req, res, next) {
  const orgId = req.headers['x-organization-id']
  if (!orgId) {
    return res.status(400).json({ error: 'Organization ID required' })
  }
  req.jobs = jobs.scope('organization', orgId)
  next()
}

app.post('/users/signup', withJobsScope, async (req, res) => {
  await req.jobs.email.sendWelcome.dispatch({
    input: { email: req.body.email, name: req.body.name },
  })
  res.json({ ok: true })
})
```

***

## Scope in Job Metadata

Jobs dispatched from scoped instances carry scope information in the `IgniterJobSearchResult`:

```typescript
const result = await jobs.email.sendWelcome.get('job_abc123').retrieve()
console.log(result.scope)
// { type: 'organization', id: 'org_123', tags: { plan: 'pro' } }
```

Use this for search and filtering:

```typescript
// Search for jobs from a specific scope
const orgJobs = await jobs.search('jobs', {
  scope: { type: 'organization', id: 'org_123' },
})
```

***

## Best Practices

* **Use `required: true`** for production multi-tenant apps to prevent unscoped dispatches
* **Keep scope types simple** — single-word identifiers like `organization`, `workspace`, `environment`
* **Use tags for metadata** — `plan`, `region`, `tier` — rather than creating many scope types
* **Validate scope IDs** — ensure IDs are valid before creating scoped instances
* **Log scope on dispatch** — add scope logging in `onStart` hooks for debugging

***

## Next Steps

* **[Search & Monitoring](/docs/jobs/search-and-monitoring)** — Find and filter jobs by scope
* **[Advanced Features](/docs/jobs/advanced-features)** — Job streams and event subscriptions with scoped instances
* **[Workers](/docs/jobs/workers)** — Workers process all scopes transparently


---

# Search & Monitoring

> Find, filter, and manage jobs and queues — search by status, inspect job details, manage queue state, and build monitoring dashboards.
URL: https://igniterjs.com/docs/jobs/search-and-monitoring

The search and monitoring APIs let you inspect jobs in your queues, track their status, manage queues programmatically, and build observability into your job processing system.

## Searching Jobs

Use `jobs.search()` to find jobs, queues, or workers:

```typescript
// Search for jobs
const failedJobs = await jobs.search('jobs', {
  status: 'failed',
  queue: 'email',
})

// Search for queues
const allQueues = await jobs.search('queues', {})

// Search for workers
const activeWorkers = await jobs.search('workers', {})
```

The `search()` method accepts a target (`'jobs'`, `'queues'`, or `'workers'`) and a filter object. The exact filter shape depends on the adapter implementation.

***

## Job Inspection

Get detailed information about a specific job:

```typescript
// Get a job instance by ID
const jobInstance = jobs.email.sendWelcome.get('job_abc123')

// Retrieve full job details
const job = await jobInstance.retrieve()
console.log(job.id)            // 'job_abc123'
console.log(job.name)          // 'sendWelcome'
console.log(job.queue)         // 'email'
console.log(job.status)        // 'completed' | 'failed' | 'active' | 'waiting' | 'delayed' | 'paused'
console.log(job.input)         // The original input payload
console.log(job.result)        // The handler return value (if completed)
console.log(job.error)         // Error message (if failed)
console.log(job.progress)      // Progress percentage (0–100)
console.log(job.attemptsMade)  // Number of execution attempts
console.log(job.priority)      // Job priority
console.log(job.createdAt)     // Creation timestamp
console.log(job.startedAt)     // When processing started
console.log(job.completedAt)   // When the job finished
console.log(job.metadata)      // Custom metadata
console.log(job.scope)         // Scope info (if dispatched from scoped instance)
```

### Job Statuses

| Status      | Description                               |
| ----------- | ----------------------------------------- |
| `waiting`   | Job is queued and waiting to be processed |
| `active`    | Job is currently being processed          |
| `completed` | Job finished successfully                 |
| `failed`    | Job failed (may be retried)               |
| `delayed`   | Job is waiting for its scheduled time     |
| `paused`    | Job is in a paused queue                  |

***

## Managing Individual Jobs

Get a job instance and control it:

```typescript
const job = jobs.email.sendWelcome.get('job_abc123')

// Check job state
const status = await job.state()        // 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused'
const progress = await job.progress()   // 0–100
const logs = await job.logs()           // Array of { timestamp, message, level } entries

// Control the job
await job.retry()                       // Retry the job (if failed)
await job.remove()                      // Remove the job permanently
await job.promote()                     // Promote a delayed job to immediate execution

// Move to failed state with a reason
await job.move('failed', 'Manual intervention required')
```

### Reading Job Logs

```typescript
const logs = await jobs.email.sendWelcome.get('job_abc123').logs()
logs.forEach((log) => {
  console.log(`[${log.timestamp.toISOString()}] [${log.level}] ${log.message}`)
})
```

***

## Bulk Operations

Use `.many()` for operations on multiple jobs:

```typescript
// Retry multiple failed jobs
await jobs.email.sendWelcome.many(['job_1', 'job_2', 'job_3']).retry()

// Remove multiple jobs
await jobs.email.sendWelcome.many(['job_4', 'job_5']).remove()
```

***

## Queue Management

Manage queues programmatically through the queue accessor:

```typescript
// Get queue details
const queueInfo = await jobs.email.get().retrieve()
console.log(queueInfo.name)       // 'email'
console.log(queueInfo.isPaused)   // false
console.log(queueInfo.jobCounts)  // { waiting: 5, active: 2, completed: 100, failed: 3, delayed: 1, paused: 0 }

// Control the queue
await jobs.email.get().pause()    // Stop processing new jobs from this queue
await jobs.email.get().resume()   // Resume processing

// Drain all jobs
const drained = await jobs.email.get().drain()
console.log(`Drained ${drained} jobs`)

// Clean completed/failed jobs
const cleaned = await jobs.email.get().clean({
  status: ['completed', 'failed'],
  olderThan: 7 * 24 * 60 * 60 * 1000, // Older than 7 days
  limit: 1000,
})
console.log(`Cleaned ${cleaned} jobs`)

// Obliterate a queue entirely (destructive!)
await jobs.email.get().obliterate({ force: true })

// Retry all failed jobs in a queue
const retried = await jobs.email.get().retryAll()
console.log(`Retried ${retried} jobs`)
```

### Clean Options

| Option      | Type                       | Description                          |
| ----------- | -------------------------- | ------------------------------------ |
| `status`    | `JobStatus \| JobStatus[]` | Statuses to clean                    |
| `olderThan` | `number`                   | Only clean jobs older than this (ms) |
| `limit`     | `number`                   | Maximum jobs to clean                |

***

## Listing Queue Jobs

List jobs in a queue with optional filters:

```typescript
// List all jobs in the email queue
const allJobs = await jobs.email.list()

// List with status filter
const failedJobs = await jobs.email.list({
  status: ['failed'],
  limit: 50,
  offset: 0,
})

// Paginate through results
const page1 = await jobs.email.list({ limit: 50, offset: 0 })
const page2 = await jobs.email.list({ limit: 50, offset: 50 })
```

***

## Worker Inspection

Search for workers and inspect their state:

```typescript
const workers = await jobs.search('workers', {})
workers.forEach((worker) => {
  console.log(worker.id)
  console.log(worker.queues)
  console.log(worker.isRunning())
  console.log(worker.isPaused())
})
```

***

## Monitoring Patterns

### Queue Health Dashboard

```typescript
async function getQueueHealth() {
  const queues = await jobs.search('queues', {})

  for (const queue of queues) {
    const info = await jobs[queue.name].get().retrieve()
    console.log(`Queue: ${queue.name}`)
    console.log(`  Paused: ${info.isPaused}`)
    console.log(`  Waiting: ${info.jobCounts.waiting}`)
    console.log(`  Active:  ${info.jobCounts.active}`)
    console.log(`  Failed:  ${info.jobCounts.failed}`)
    console.log(`  Delayed: ${info.jobCounts.delayed}`)
  }
}
```

### Alert on Failed Jobs

```typescript
async function monitorFailures() {
  const failedJobs = await jobs.search('jobs', {
    status: 'failed',
  })

  if (failedJobs.length > 50) {
    await alerts.send({
      level: 'critical',
      message: `${failedJobs.length} failed jobs detected`,
    })
  }
}
```

### Find Stale Jobs

```typescript
async function findStaleJobs() {
  const staleThreshold = Date.now() - 60 * 60 * 1000 // 1 hour ago

  const activeJobs = await jobs.search('jobs', {
    status: 'active',
  })

  const stale = activeJobs.filter(
    (job) => job.startedAt && job.startedAt.getTime() < staleThreshold
  )

  for (const job of stale) {
    console.log(`Stale job: ${job.name} (${job.id}) — started ${job.startedAt}`)
  }

  return stale
}
```

***

## Best Practices

* **Use status filters** — narrow searches to avoid loading all jobs at once
* **Paginate results** — use `limit` and `offset` for large queues
* **Clean regularly** — clean completed/failed jobs to keep queues manageable
* **Monitor failure rates** — set up alerts for abnormal failure spikes
* **Track stale jobs** — detect jobs that are active for too long
* **Use metadata for filtering** — attach meaningful metadata to jobs for search

***

## Next Steps

* **[Advanced Features](/docs/jobs/advanced-features)** — Job streams, event subscriptions, and telemetry
* **[Workers](/docs/jobs/workers)** — Worker configuration and lifecycle management
* **[Scopes](/docs/jobs/scopes)** — Search scoped jobs with scope filters


---

# Workers

> Create and manage workers with the fluent builder — configure concurrency, rate limiters, lifecycle hooks, and process jobs from one or multiple queues.
URL: https://igniterjs.com/docs/jobs/workers

Workers are the processes that execute your background jobs. They continuously poll the backend (Redis, SQLite, or memory) for new jobs and execute them according to your configuration.

## The Worker Builder

Workers are created through the fluent builder at `jobs.worker.create()`:

```typescript
const worker = await jobs.worker.create()
  .addQueue('email')
  .withConcurrency(5)
  .onActive(({ job }) => {
    console.log(`Processing: ${job.name} (${job.id})`)
  })
  .onSuccess(({ job, result }) => {
    console.log(`Completed: ${job.name}`)
  })
  .onFailure(({ job, error }) => {
    console.error(`Failed: ${job.name} — ${error.message}`)
  })
  .start()

console.log(`Worker started: ${worker.id}`)
```

### Worker Builder Methods

| Method                  | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `.addQueue(name)`       | Add a queue for this worker to process                       |
| `.withConcurrency(n)`   | Set maximum concurrent job executions                        |
| `.withLimiter(limiter)` | Apply a rate limiter to this worker                          |
| `.onActive(handler)`    | Called when a job starts processing                          |
| `.onSuccess(handler)`   | Called when a job completes successfully                     |
| `.onFailure(handler)`   | Called when a job fails                                      |
| `.onIdle(handler)`      | Called when no jobs are available                            |
| `.start()`              | Build and start the worker (returns `Promise<WorkerHandle>`) |

***

## Auto-Start Workers

For simpler setups, configure workers to start automatically when the jobs runtime is built:

```typescript
const jobs = IgniterJobs.create()
  .withAdapter(IgniterJobsBullMQAdapter.create({ redis }))
  .withService('my-api')
  .withEnvironment('production')
  .withContext(async () => ({ db, mailer }))
  .addQueue(emailQueue)
  .addQueue(analyticsQueue)
  .withAutoStartWorker({
    queues: ['email', 'analytics'],
    concurrency: 5,
  })
  .build()
// Workers start automatically — no manual start() needed
```

### Auto-Start Options

| Option        | Type                | Description                |
| ------------- | ------------------- | -------------------------- |
| `queues`      | `string[]`          | Queue names to process     |
| `concurrency` | `number`            | Concurrent job limit       |
| `limiter`     | `{ max, duration }` | Rate limiter configuration |

***

## Worker-Level Defaults

Apply default worker configuration across all workers via `withWorkerDefaults()`:

```typescript
const jobs = IgniterJobs.create()
  .withAdapter(...)
  .withService('my-api')
  .withEnvironment('production')
  .withContext(async () => ({ db }))
  .withWorkerDefaults({
    concurrency: 5,
  })
  .addQueue(emailQueue)
  .addQueue(analyticsQueue)
  .build()
```

***

## Concurrency Control

Control how many jobs run simultaneously per worker:

```typescript
// CPU-intensive jobs — low concurrency
const cpuWorker = await jobs.worker.create()
  .addQueue('image-processing')
  .withConcurrency(2)
  .start()

// I/O-bound jobs — high concurrency
const ioWorker = await jobs.worker.create()
  .addQueue('email')
  .addQueue('notifications')
  .withConcurrency(50)
  .start()

// Critical jobs — one at a time
const criticalWorker = await jobs.worker.create()
  .addQueue('payment')
  .withConcurrency(1)
  .start()
```

<Callout type="info" title="Choosing Concurrency">
  * **CPU-intensive**: 2–5 to avoid contention
  * **I/O-bound**: 10–50 to maximize throughput
  * **Database-heavy**: 5–10 to avoid pool exhaustion
  * **Critical/ordered**: 1 for sequential processing
</Callout>

***

## Rate Limiters

Apply rate limiters to control throughput at the worker level:

```typescript
const worker = await jobs.worker.create()
  .addQueue('email')
  .withConcurrency(5)
  .withLimiter({
    max: 100,        // Maximum jobs
    duration: 60_000, // Per 60 seconds (1 minute)
  })
  .start()
// Processes at most 100 jobs per minute
```

Rate limiters can also be set per-job through the [dispatch options](/docs/jobs/job-definitions#available-dispatch-options).

***

## Lifecycle Event Handlers

React to worker lifecycle events with typed handlers:

### onActive

Called when a job starts processing:

```typescript
.onActive(({ job }) => {
  console.log(`[${job.queue}] Processing ${job.name} (${job.id})`)
  metrics.increment('jobs.active', { queue: job.queue })
})
```

### onSuccess

Called when a job completes successfully:

```typescript
.onSuccess(({ job, result }) => {
  console.log(`[${job.queue}] Completed ${job.name} in ${Date.now() - job.createdAt.getTime()}ms`)
  metrics.increment('jobs.completed', { queue: job.queue })
})
```

### onFailure

Called when a job fails:

```typescript
.onFailure(({ job, error }) => {
  console.error(`[${job.queue}] Failed ${job.name}: ${error.message}`)
  metrics.increment('jobs.failed', { queue: job.queue })

  if (job.attemptsMade >= 3) {
    alerts.send({ type: 'critical', message: `Job exhausted retries: ${job.name}` })
  }
})
```

### onIdle

Called when no jobs are available:

```typescript
.onIdle(() => {
  console.log('Worker idle — no jobs in queue')
})
```

### Handler Context

| Handler     | Context Properties                               |
| ----------- | ------------------------------------------------ |
| `onActive`  | `job: IgniterJobSearchResult`                    |
| `onSuccess` | `job: IgniterJobSearchResult`, `result: unknown` |
| `onFailure` | `job: IgniterJobSearchResult`, `error: Error`    |
| `onIdle`    | *(none)*                                         |

***

## Multiple Workers

Run multiple workers for the same queue (horizontal scaling) or different queues (isolation):

```typescript
// Two workers sharing the email queue (horizontal scaling)
const emailWorker1 = await jobs.worker.create()
  .addQueue('email').withConcurrency(5).start()

const emailWorker2 = await jobs.worker.create()
  .addQueue('email').withConcurrency(5).start()

// Dedicated worker for critical queue
const paymentWorker = await jobs.worker.create()
  .addQueue('payment').withConcurrency(1)
  .onFailure(({ job, error }) => {
    alerts.send({ type: 'critical', message: `Payment job failed: ${job.name}` })
  })
  .start()
```

Multiple workers on the same queue automatically share the workload — think of it as horizontal scaling for job processing.

***

## Worker Handle

The `WorkerHandle` returned by `.start()` gives you runtime control:

```typescript
const worker = await jobs.worker.create()
  .addQueue('email')
  .start()

// Inspect state
console.log(worker.id)           // Unique worker ID
console.log(worker.queues)       // ['email']
console.log(worker.isRunning())  // true
console.log(worker.isPaused())   // false

// Control lifecycle
await worker.pause()             // Stop processing new jobs
await worker.resume()            // Resume processing
console.log(worker.isPaused())   // true

// Get metrics
const metrics = await worker.getMetrics()
console.log(metrics.processed)   // Number of jobs processed
console.log(metrics.failed)      // Number of failed jobs
console.log(metrics.avgDuration) // Average job duration in ms
console.log(metrics.concurrency) // Current concurrency
console.log(metrics.uptime)      // Uptime in milliseconds

// Shut down
await worker.close()
console.log(worker.isClosed())   // true
```

***

## Graceful Shutdown

Always shut down workers gracefully before your application exits:

```typescript
// Shut down all workers and close adapter connections
await jobs.shutdown()

// Or close individual workers
await worker.close()
```

In production, handle OS signals:

```typescript
process.on('SIGTERM', async () => {
  console.log('SIGTERM received — shutting down gracefully...')
  await jobs.shutdown()
  process.exit(0)
})

process.on('SIGINT', async () => {
  console.log('SIGINT received — shutting down...')
  await jobs.shutdown()
  process.exit(0)
})
```

<Callout type="warn" title="Graceful Shutdown Matters">
  Always call `shutdown()` before exiting. This ensures:

  * In-flight jobs complete or are properly requeued
  * Redis/SQLite connections are closed cleanly
  * No jobs are lost during the shutdown window
</Callout>

***

## Real-World Patterns

### Priority-Based Workers

Run separate workers for different priority levels:

```typescript
// High-priority worker — immediate processing, low concurrency
const highPriorityWorker = await jobs.worker.create()
  .addQueue('priority-high')
  .withConcurrency(1)
  .onFailure(({ job, error }) => {
    alerts.send({ type: 'critical', message: `High-priority job failed: ${job.name}` })
  })
  .start()

// Normal worker — standard processing
const normalWorker = await jobs.worker.create()
  .addQueue('default')
  .withConcurrency(10)
  .start()
```

### Monitoring with Metrics

```typescript
const worker = await jobs.worker.create()
  .addQueue('email')
  .withConcurrency(10)
  .onActive(({ job }) => {
    prometheus.activeJobs.inc({ queue: job.queue })
  })
  .onSuccess(({ job }) => {
    prometheus.activeJobs.dec({ queue: job.queue })
    prometheus.completedJobs.inc({ queue: job.queue })
  })
  .onFailure(({ job }) => {
    prometheus.activeJobs.dec({ queue: job.queue })
    prometheus.failedJobs.inc({ queue: job.queue })
  })
  .start()
```

***

## Best Practices

* **Set appropriate concurrency** — match to your workload type
* **Use rate limiters** — protect downstream services from being overwhelmed
* **Handle shutdown gracefully** — always call `shutdown()` or `close()`
* **Monitor worker health** — track processed, failed, and active job counts
* **Separate workers by priority** — critical jobs get dedicated low-concurrency workers
* **Scale horizontally** — run multiple workers on the same queue for redundancy

***

## Troubleshooting

### Workers Not Processing

**Problem**: Jobs are queued but not executing.

**Solutions**:

* Verify the worker's `addQueue('email')` matches the queue name exactly
* Check that `start()` was called (auto-start or manual)
* Verify Redis/SQLite connectivity
* Check for unhandled errors in the worker initialization

### High Memory Usage

**Problem**: Worker consumes too much memory.

**Solutions**:

* Reduce concurrency — fewer concurrent jobs means less memory
* Check for memory leaks in job handlers (accumulating arrays, unclosed connections)
* Monitor per-job memory usage

### Worker Crashes

**Problem**: Worker crashes unexpectedly.

**Solutions**:

* Add error handling in lifecycle hooks — hooks throwing errors shouldn't crash the worker
* Use a process manager (PM2, systemd) to restart crashed workers
* Monitor logs for unhandled rejections

***

## Next Steps

* **[Scopes](/docs/jobs/scopes)** — Multi-tenant isolation with scoped instances
* **[Search & Monitoring](/docs/jobs/search-and-monitoring)** — Find and manage jobs
* **[Advanced Features](/docs/jobs/advanced-features)** — Job streams, events, and telemetry


---

# Advanced Features

> Visual log formatting with groups and separators, runtime level changes, flush strategies, error handling, and the full log() method.
URL: https://igniterjs.com/docs/logger/advanced

## Advanced Features

Beyond basic logging, Logger provides visual formatting tools, runtime control, and fine-grained APIs for production use.

***

## Visual Formatting

### Groups

Use `group()` and `groupEnd()` to create indented sections in console output:

```typescript
import { IgniterLogger } from '@igniter-js/logger';

const logger = IgniterLogger.create()
  .addTransport({ target: 'console', options: { pretty: true } })
  .build();

logger.group('User Import');
logger.info('Reading CSV file...');
logger.info('Parsing 1,423 records...');
logger.debug('Record 1: { name: "Alice" }');
logger.debug('Record 2: { name: "Bob" }');
logger.success('Import complete');
logger.groupEnd();

logger.info('Next task starting...');
```

Console output:

```
┌ User Import
  Reading CSV file...
  Parsing 1,423 records...
  Record 1: { name: "Alice" }
  Record 2: { name: "Bob" }
  ✓ Import complete
Next task starting...
```

Groups are **nestable** — each `group()` call increments the indent level:

```typescript
logger.group('Deployment');
logger.info('Step 1: Build');

logger.group('Docker');
logger.info('Building image...');
logger.info('Tagging image...');
logger.groupEnd();

logger.info('Step 2: Deploy');
logger.groupEnd();
```

Output:

```
┌ Deployment
  Step 1: Build
  ┌ Docker
    Building image...
    Tagging image...
  Step 2: Deploy
```

<Callout type="info">
  Groups only affect **console output**. File and HTTP transports receive the raw messages without indentation.
</Callout>

### Separators

Draw visual dividers with `separator()`:

```typescript
logger.separator();
// ──────────────────────────────────────────────────

logger.info('Section 1 content');
logger.info('More section 1');

logger.separator();

logger.info('Section 2 content');
```

Output:

```
──────────────────────────────────────────────────
Section 1 content
More section 1
──────────────────────────────────────────────────
Section 2 content
```

***

## Success Messages

`success()` is a convenience method that logs at `info` level with a `✓` prefix and a `type: "success"` field:

```typescript
logger.success('Database connection established');
// [12:34:56] INFO: ✓ Database connection established
// (also includes { type: "success" } in structured output)

// Equivalent to:
// logger.info('✓ Database connection established', { type: 'success' });
```

***

## Runtime Control

### Changing Log Level

Use `setLevel()` to change the minimum log level at runtime — useful for toggling debug output without restarting:

```typescript
import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

const logger = IgniterLogger.create()
  .withLevel(IgniterLogLevel.Info)
  .build();

logger.debug('Not logged');      // Below Info — suppressed
logger.setLevel(IgniterLogLevel.Debug);
logger.debug('Now logged');      // Visible after level change
```

### Changing App Name and Component

Update `appName` and `component` at runtime:

```typescript
logger.setAppName('worker-v2');
logger.setComponent('scheduler');

logger.info('Running job');
// Includes appName=worker-v2, component=scheduler
```

Pass `undefined` to clear:

```typescript
logger.setAppName(undefined);
logger.setComponent(undefined);
```

***

## The `log()` Method

When you need programmatic control over the log level, use the generic `log()` method:

```typescript
logger.log('error', 'Something went wrong', { code: 500 }, new Error('boom'));
logger.log('info', 'Operation complete', { duration: 42 });

// Evaluates level dynamically
function logAtDynamicLevel(
  logger: ReturnType<typeof IgniterLogger.create>,
  severity: 'low' | 'high',
  message: string,
) {
  const level = severity === 'high' ? 'error' : 'debug';
  logger.log(level, message);
}
```

### Signature

```typescript
log(
  level: IgniterLogLevel | string,
  message: string,
  context?: Record<string, unknown> | string,
  error?: Error | unknown,
): void
```

| Parameter | Type                                                           | Description                                                          |
| --------- | -------------------------------------------------------------- | -------------------------------------------------------------------- |
| `level`   | `"fatal" \| "error" \| "warn" \| "info" \| "debug" \| "trace"` | Log level.                                                           |
| `message` | `string`                                                       | The log message.                                                     |
| `context` | `Record<string, unknown> \| string`                            | Optional context payload. Strings are wrapped as `{ label: value }`. |
| `error`   | `Error \| unknown`                                             | Optional error object. Set as `err` in the structured payload.       |

***

## Flush Strategies

### Graceful Shutdown

For file and HTTP transports, flush buffered logs before process exit:

```typescript
import { IgniterLogger } from '@igniter-js/logger';

const logger = IgniterLogger.create()
  .addTransport({ target: 'file', options: { path: './logs/app.log' } })
  .addTransport({ target: 'http', options: { url: process.env.LOG_URL! } })
  .build();

// SIGTERM (e.g., Docker stop, Kubernetes pod termination)
process.on('SIGTERM', async () => {
  logger.info('Received SIGTERM — flushing logs');
  await logger.flush();
  process.exit(0);
});

// SIGINT (Ctrl+C)
process.on('SIGINT', async () => {
  logger.info('Received SIGINT — flushing logs');
  await logger.flush();
  process.exit(0);
});

// beforeExit (natural exit)
process.on('beforeExit', async () => {
  await logger.flush();
});
```

### What `flush()` Does

| Transport    | Behavior                                                           |
| ------------ | ------------------------------------------------------------------ |
| **Console**  | No-op (console writes are synchronous).                            |
| **File**     | Flushes Pino's internal buffer to disk.                            |
| **HTTP**     | Sends all buffered log entries to the remote endpoint immediately. |
| **External** | Delegates to the transport's flush mechanism if available.         |

<Callout type="warn">
  **Always call `flush()` before process exit** when using file or HTTP transports. Unflushed logs are lost. The HTTP transport timer uses `.unref()` — it won't keep the process alive.
</Callout>

***

## Error Handling

### Logging Errors

Pass `Error` objects as the second argument to `error()` and `fatal()`:

```typescript
try {
  await dangerousOperation();
} catch (err) {
  logger.error('Operation failed', err);
  // Structured output includes: { err: { message, stack, ... } }
}
```

### Logger Errors Are Non-Fatal

Logger never throws from `log()`, `info()`, `error()`, etc. Transport failures are handled silently:

```typescript
// Even with an invalid file path, logging won't crash your app
const logger = IgniterLogger.create()
  .addTransport({
    target: 'file',
    options: { path: '/invalid/path/app.log' },
  })
  .build();

logger.info('Application still running');
// No exception thrown — the file transport may fail silently
```

### Custom Error Classes

Logger exports typed error classes for programmatic error handling:

```typescript
import {
  IgniterLoggerError,
  IGNITER_LOGGER_ERROR_CODES,
} from '@igniter-js/logger';

try {
  // Your logger setup
} catch (err) {
  if (err instanceof IgniterLoggerError) {
    switch (err.code) {
      case IGNITER_LOGGER_ERROR_CODES.TRANSPORT_INVALID:
        console.error('Invalid transport target:', err.details);
        break;
      case IGNITER_LOGGER_ERROR_CODES.CONFIG_INVALID:
        console.error('Invalid configuration:', err.message);
        break;
    }
  }
}
```

***

## Complete Log Level Reference

| Level   | Method                         | Typical Use                                        |
| ------- | ------------------------------ | -------------------------------------------------- |
| `fatal` | `logger.fatal(msg, err?)`      | Unrecoverable errors — service is going down       |
| `error` | `logger.error(msg, err?)`      | Operation failures, exceptions                     |
| `warn`  | `logger.warn(msg, ...args)`    | Degraded state, deprecation warnings               |
| `info`  | `logger.info(msg, ...args)`    | Normal operations, state transitions               |
| `debug` | `logger.debug(msg, ...args)`   | Development details, variable inspection           |
| `trace` | `logger.trace(msg, ...args)`   | Extremely granular — function entry/exit           |
| —       | `logger.success(msg, ...args)` | Positive outcomes: starts, completions, milestones |

***

## Next Steps

<Cards>
  <Card title="API Reference" description="Complete reference for every builder method, manager operation, type, and error class." href="/docs/logger/api-reference" />

  <Card title="Troubleshooting" description="Common errors, transport failures, level issues, and how to fix them." href="/docs/logger/troubleshooting" />

  <Card title="Best Practices" description="Do's and Don'ts for production logging with structured context." href="/docs/logger/best-practices" />
</Cards>


---

# API Reference

> Complete API reference for @igniter-js/logger — builder, manager, types, enums, transport configurations, and error classes.
URL: https://igniterjs.com/docs/logger/api-reference

## API Reference

This reference documents every public export of `@igniter-js/logger`. All examples are verified against the implementation in [`packages/logger/src/`](https://github.com/igniter-js/igniter-js/tree/main/packages/logger/src).

***

## Exports

```typescript
// Builder (primary entry point)
import { IgniterLogger, IgniterLoggerBuilder } from '@igniter-js/logger';

// Manager (produced by .build())
import { IgniterLoggerManager } from '@igniter-js/logger';

// Enums
import { IgniterLogLevel } from '@igniter-js/logger';

// Types
import type {
  IIgniterLoggerManager,
  IgniterLoggerConfig,
  IgniterLoggerBuilderState,
  IgniterTransportConfig,
  ConsoleTransportOptions,
  FileTransportOptions,
  HttpTransportOptions,
  IgniterFileTransportRotationOptions,
} from '@igniter-js/logger';

// Errors
import {
  IgniterLoggerError,
  IGNITER_LOGGER_ERROR_CODES,
  type IgniterLoggerErrorCode,
} from '@igniter-js/logger';
```

***

## `IgniterLogger` / `IgniterLoggerBuilder`

The primary entry point. `IgniterLogger` is an alias for `IgniterLoggerBuilder`. Both are the same class.

### `IgniterLogger.create()`

Creates a new builder instance.

```typescript
static create(): IgniterLoggerBuilder<{}>
```

**Returns:** A new `IgniterLoggerBuilder` with empty state.

```typescript
const builder = IgniterLogger.create();
```

***

### `.withLevel(level)`

Sets the minimum log level. Messages below this level are suppressed.

```typescript
withLevel(level: IgniterLogLevel): IgniterLoggerBuilder<TScopes>
```

| Parameter | Type              | Description                                                                    |
| --------- | ----------------- | ------------------------------------------------------------------------------ |
| `level`   | `IgniterLogLevel` | Minimum log level. Values: `Fatal`, `Error`, `Warn`, `Info`, `Debug`, `Trace`. |

```typescript
const logger = IgniterLogger.create()
  .withLevel(IgniterLogLevel.Info)
  .build();

logger.debug('Not logged');  // below Info — dropped
logger.info('Logged');        // Info — logged
```

***

### `.withAppName(name)`

Sets the application name included in every log entry.

```typescript
withAppName(appName: string): IgniterLoggerBuilder<TScopes>
```

| Parameter | Type     | Description                                                             |
| --------- | -------- | ----------------------------------------------------------------------- |
| `appName` | `string` | Application name label. Pino sets this as `appName` in the base object. |

```typescript
const logger = IgniterLogger.create()
  .withAppName('api')
  .build();

logger.info('Started');
// Structured output: { appName: "api", msg: "Started", ... }
```

***

### `.withComponent(component)`

Sets the component name included in every log entry.

```typescript
withComponent(component: string): IgniterLoggerBuilder<TScopes>
```

| Parameter   | Type     | Description                      |
| ----------- | -------- | -------------------------------- |
| `component` | `string` | Component label for log entries. |

```typescript
const logger = IgniterLogger.create()
  .withComponent('http')
  .build();

logger.info('Request');
// Structured output: { component: "http", msg: "Request", ... }
```

***

### `.withContext(context)`

Merges default context into every log entry. Subsequent calls merge (not replace).

```typescript
withContext(context: Record<string, unknown>): IgniterLoggerBuilder<TScopes>
```

| Parameter | Type                      | Description                                    |
| --------- | ------------------------- | ---------------------------------------------- |
| `context` | `Record<string, unknown>` | Context data merged into the Pino base object. |

```typescript
const logger = IgniterLogger.create()
  .withContext({ region: 'us-east-1' })
  .withContext({ version: '2.0' })  // merges
  .build();

logger.info('Deploy');
// Structured output: { region: "us-east-1", version: "2.0", msg: "Deploy", ... }
```

***

### `.addTransport(transport)`

Adds a transport configuration. Call multiple times for multi-transport logging.

```typescript
addTransport(transport: IgniterTransportConfig): IgniterLoggerBuilder<TScopes>
```

| Parameter   | Type                     | Description                                       |
| ----------- | ------------------------ | ------------------------------------------------- |
| `transport` | `IgniterTransportConfig` | Transport descriptor with `target` and `options`. |

```typescript
const logger = IgniterLogger.create()
  .addTransport({ target: 'console', options: { pretty: true } })
  .addTransport({ target: 'file', options: { path: './logs/app.log' } })
  .build();
```

See [Transports](/docs/logger/transports) for all transport options and external transports.

***

### `.defineScopes<T>()`

Defines the typed scope shape for child loggers. Changes the generic parameter on the builder.

```typescript
defineScopes<T extends Record<string, unknown>>(): IgniterLoggerBuilder<T>
```

```typescript
const logger = IgniterLogger.create()
  .defineScopes<{ tenantId: string }>()
  .build();

// TypeScript enforces tenantId on child context
const child = logger.child('tenant', { tenantId: 't-1' });
```

***

### `.build()`

Builds the `IgniterLoggerManager` instance. If no transports were configured, a console transport with pretty formatting is added by default.

```typescript
build(): IgniterLoggerManager<TScopes>
```

**Returns:** A fully configured `IgniterLoggerManager` instance.

```typescript
const logger = IgniterLogger.create()
  .withLevel(IgniterLogLevel.Info)
  .withAppName('api')
  .build();
// Ready to use: logger.info(...), logger.error(...), etc.
```

***

## `IgniterLoggerManager`

The logger instance returned by `.build()`. Wraps a Pino instance and exposes all log methods.

### Log Methods

#### `.fatal(message, error?)`

Log a fatal-level message. Use for unrecoverable errors.

```typescript
fatal(message: string, error?: Error | unknown): void
```

```typescript
logger.fatal('Database unreachable', new Error('ECONNREFUSED'));
```

#### `.error(message, error?)`

Log an error-level message.

```typescript
error(message: string, error?: Error | unknown): void
```

```typescript
logger.error('Payment failed', new Error('Insufficient funds'));
```

#### `.warn(message, ...args)`

Log a warning-level message.

```typescript
warn(message: string, ...args: any[]): void
```

```typescript
logger.warn('Rate limit approaching', { remaining: 10 });
```

#### `.info(message, ...args)`

Log an informational message.

```typescript
info(message: string, ...args: any[]): void
```

```typescript
logger.info('Server started on port 3000');
logger.info('User fetched', { userId: 'u-123', duration: 42 });
```

#### `.debug(message, ...args)`

Log a debug-level message.

```typescript
debug(message: string, ...args: any[]): void
```

```typescript
logger.debug('Query parameters', { page: 1, limit: 25 });
```

#### `.trace(message, ...args)`

Log a trace-level message. Most granular.

```typescript
trace(message: string, ...args: any[]): void
```

```typescript
logger.trace('Entering function', { fn: 'processOrder', args: [42] });
```

#### `.success(message, ...args)`

Log a success message at `info` level with a `✓` prefix and `type: "success"`.

```typescript
success(message: string, ...args: any[]): void
```

```typescript
logger.success('Deployment complete');
// Console: [12:34:56] INFO: ✓ Deployment complete
// Structured: { type: "success", msg: "✓ Deployment complete", ... }
```

#### `.log(level, message, context?, error?)`

Generic log method — programmatic level selection.

```typescript
log(
  level: IgniterLogLevel | string,
  message: string,
  context?: Record<string, unknown> | string,
  error?: Error | unknown,
): void
```

| Parameter | Type                                                           | Description                                         |
| --------- | -------------------------------------------------------------- | --------------------------------------------------- |
| `level`   | `"fatal" \| "error" \| "warn" \| "info" \| "debug" \| "trace"` | Log level.                                          |
| `message` | `string`                                                       | The log message.                                    |
| `context` | `Record<string, unknown> \| string`                            | Context payload. Strings become `{ label: value }`. |
| `error`   | `Error \| unknown`                                             | Error object — set as `err` in the payload.         |

***

### Formatting Methods

#### `.group(name?)`

Start a log group. Increases indentation level for console output.

```typescript
group(name?: string): void
```

| Parameter | Type     | Description                                |
| --------- | -------- | ------------------------------------------ |
| `name`    | `string` | Optional group label. Printed as `┌ name`. |

#### `.groupEnd()`

End the current log group. Decreases indentation level.

```typescript
groupEnd(): void
```

#### `.separator()`

Draw a visual separator line (50 `─` characters).

```typescript
separator(): void
```

***

### Child Logger

#### `.child(componentName, context?)`

Creates a child logger with merged context.

```typescript
child(
  componentName: string,
  context?: Record<string, unknown> | string,
): IIgniterLoggerManager
```

| Parameter       | Type                                | Description                                                        |
| --------------- | ----------------------------------- | ------------------------------------------------------------------ |
| `componentName` | `string`                            | Component name for the child logger. Overrides parent's component. |
| `context`       | `Record<string, unknown> \| string` | Context merged into child entries.                                 |

**Returns:** A new `IgniterLoggerManager` instance sharing the parent's Pino instance.

***

### Runtime Control

#### `.setLevel(level)`

Change the minimum log level at runtime.

```typescript
setLevel(level: IgniterLogLevel | string): void
```

```typescript
logger.setLevel(IgniterLogLevel.Debug);
```

#### `.setAppName(appName)`

Change the application name at runtime. Pass `undefined` to clear.

```typescript
setAppName(appName: string | undefined): void
```

#### `.setComponent(componentName)`

Change the component name at runtime. Pass `undefined` to clear.

```typescript
setComponent(componentName: string | undefined): void
```

#### `.flush()`

Flush any buffered log entries. Critical before process exit for file and HTTP transports.

```typescript
flush(): Promise<void>
```

**Returns:** A Promise that resolves when all buffered logs are written.

***

## `IgniterLogLevel`

Enum of supported log levels.

```typescript
enum IgniterLogLevel {
  Fatal = "fatal",
  Error = "error",
  Warn  = "warn",
  Info  = "info",
  Debug = "debug",
  Trace = "trace",
}
```

| Member  | Value     | Pino Level | Typical Use              |
| ------- | --------- | ---------- | ------------------------ |
| `Fatal` | `"fatal"` | 60         | System is unusable       |
| `Error` | `"error"` | 50         | Runtime errors           |
| `Warn`  | `"warn"`  | 40         | Warnings, degraded state |
| `Info`  | `"info"`  | 30         | Normal operations        |
| `Debug` | `"debug"` | 20         | Development details      |
| `Trace` | `"trace"` | 10         | Extremely granular       |

***

## Transport Types

### `IgniterTransportConfig`

Configuration descriptor for a transport.

```typescript
interface IgniterTransportConfig<TOptions = IgniterTransportOptions> {
  target: IgniterTransportTarget;
  options?: TOptions;
}
```

| Field     | Type                                                                                                 | Description                  |
| --------- | ---------------------------------------------------------------------------------------------------- | ---------------------------- |
| `target`  | `"console" \| "file" \| "http" \| string`                                                            | Transport target identifier. |
| `options` | `ConsoleTransportOptions \| FileTransportOptions \| HttpTransportOptions \| Record<string, unknown>` | Transport-specific options.  |

### `ConsoleTransportOptions`

```typescript
interface ConsoleTransportOptions {
  colorize?: boolean;       // default: true
  pretty?: boolean;          // default: true
  destination?: "stdout" | "stderr" | string;  // default: "stdout"
  translateTime?: string | boolean;  // default: "SYS:standard"
}
```

### `FileTransportOptions`

```typescript
interface FileTransportOptions {
  path: string;              // required — destination file path
  mkdir?: boolean;           // default: true — create parent dirs
  rotation?: boolean | IgniterFileTransportRotationOptions;  // default: false
}
```

### `IgniterFileTransportRotationOptions`

```typescript
interface IgniterFileTransportRotationOptions {
  maxSizeBytes?: number;     // max file size before rotation
  maxFiles?: number;         // max rotated files to keep
  intervalMs?: number;       // rotation interval in ms
}
```

### `HttpTransportOptions`

```typescript
interface HttpTransportOptions {
  url: string;               // required — target URL for log ingestion
  headers?: Record<string, string>;  // HTTP headers (auth, metadata)
  batchSize?: number;        // default: 10 — entries per batch
  timeoutMs?: number;        // default: 5000 — request timeout
  flushInterval?: number;    // default: 5000 — periodic flush ms
}
```

***

## Configuration Types

### `IgniterLoggerBuilderState`

Internal builder state. Used by the builder to accumulate configuration.

```typescript
interface IgniterLoggerBuilderState {
  level?: IgniterLogLevel;
  appName?: string;
  component?: string;
  context?: Record<string, unknown>;
  transports?: IgniterTransportConfig[];
  scopes?: Record<string, unknown>;
}
```

### `IgniterLoggerConfig`

Final configuration passed to the manager.

```typescript
interface IgniterLoggerConfig {
  level?: IgniterLogLevel;
  appName?: string;
  component?: string;
  context?: Record<string, unknown>;
  transports?: IgniterTransportConfig[];
  scopes?: Record<string, unknown>;
}
```

***

## Error Classes

### `IgniterLoggerError`

Custom error class extending `IgniterError` from `@igniter-js/common`.

```typescript
class IgniterLoggerError extends IgniterError {
  constructor(
    code: IgniterLoggerErrorCode,
    message: string,
    details?: {
      'ctx.package': string;
      'ctx.operation': string;
      'ctx.state'?: Record<string, unknown>;
    }
  );

  static transportInvalid(transport: string, operation: string): IgniterLoggerError;
  static levelInvalid(level: string, operation: string): IgniterLoggerError;
  static configInvalid(reason: string, operation: string): IgniterLoggerError;
  static flushFailed(cause: string, operation: string): IgniterLoggerError;
}
```

### `IGNITER_LOGGER_ERROR_CODES`

```typescript
const IGNITER_LOGGER_ERROR_CODES = {
  TRANSPORT_INVALID: 'TRANSPORT_INVALID',
  LEVEL_INVALID: 'LEVEL_INVALID',
  CONFIG_INVALID: 'CONFIG_INVALID',
  FLUSH_FAILED: 'FLUSH_FAILED',
} as const;
```

| Code                | Meaning                                  |
| ------------------- | ---------------------------------------- |
| `TRANSPORT_INVALID` | Unknown or unsupported transport target. |
| `LEVEL_INVALID`     | Unknown log level string.                |
| `CONFIG_INVALID`    | Invalid or missing configuration.        |
| `FLUSH_FAILED`      | Flush operation failed (I/O error).      |

### `IgniterLoggerErrorCode`

```typescript
type IgniterLoggerErrorCode =
  typeof IGNITER_LOGGER_ERROR_CODES[keyof typeof IGNITER_LOGGER_ERROR_CODES];
```

***

## Manager Interface

### `IIgniterLoggerManager`

The public interface implemented by `IgniterLoggerManager`.

```typescript
interface IIgniterLoggerManager extends IIgniterLogger {
  child(componentName: string, context?: Record<string, unknown> | string): IIgniterLoggerManager;
  success(message: string, ...args: any[]): void;
  group(name?: string): void;
  groupEnd(): void;
  separator(): void;
  setLevel(level: IgniterLogLevel | string): void;
  setAppName(appName: string | undefined): void;
  setComponent(componentName: string | undefined): void;
  flush(): Promise<void>;
}
```

***

## Next Steps

<Cards>
  <Card title="Troubleshooting" description="Common errors, transport failures, and how to debug them." href="/docs/logger/troubleshooting" />

  <Card title="Best Practices" description="Production logging patterns, structured context, and anti-patterns." href="/docs/logger/best-practices" />

  <Card title="Framework Integration" description="Use logger with Next.js, Express, Fastify, and NestJS." href="/docs/logger/framework-integration" />
</Cards>


---

# Best Practices

> Production logging patterns, structured context conventions, and common anti-patterns to avoid with @igniter-js/logger.
URL: https://igniterjs.com/docs/logger/best-practices

## Best Practices

Guidelines for effective, maintainable, and performant logging with `@igniter-js/logger`.

***

## ✅ Do's

### 1. Always set `appName` and `component`

These fields identify the source of every log entry — essential in multi-service environments:

```typescript
// ✅ Good — identifiable in aggregated logs
const logger = IgniterLogger.create()
  .withAppName('payment-service')
  .withComponent('stripe')
  .build();
```

### 2. Use structured context instead of string interpolation

Pino is a structured logger. Pass data as objects, not string concatenation:

```typescript
// ✅ Good — queryable, filterable
logger.info('User created', { userId: 'u-123', plan: 'pro' });

// ❌ Bad — can't filter or query
logger.info(`User u-123 created with pro plan`);
```

### 3. Create child loggers for request-scoped context

Avoid passing `requestId` to every log call:

```typescript
// ✅ Good — requestId is set once on the child
const reqLogger = logger.child('http', { requestId: crypto.randomUUID() });
reqLogger.info('Request received');
reqLogger.info('Response sent', { statusCode: 200 });

// ❌ Bad — repeating requestId everywhere
logger.info('Request received', { requestId });
logger.info('Response sent', { requestId, statusCode: 200 });
```

### 4. Flush before process exit

Always flush when using file or HTTP transports:

```typescript
// ✅ Good
process.on('SIGTERM', async () => {
  logger.info('Shutting down');
  await logger.flush();
  process.exit(0);
});
```

### 5. Use the right log level

Choose the appropriate level for each message:

| Level   | When to Use                                                                |
| ------- | -------------------------------------------------------------------------- |
| `fatal` | Service cannot continue — database is down, port in use                    |
| `error` | Operation failed but service continues — API call failed, validation error |
| `warn`  | Degraded but functional — retry, fallback used, deprecated API             |
| `info`  | Normal operations — server started, user created, job completed            |
| `debug` | Development details — query parameters, intermediate state                 |
| `trace` | Extremely granular — function entry/exit, loop iterations                  |

### 6. Configure transports per environment

```typescript
const isDev = process.env.NODE_ENV !== 'production';

const logger = IgniterLogger.create()
  .withLevel(isDev ? IgniterLogLevel.Debug : IgniterLogLevel.Info)
  .withAppName('api');

// Always log to console — pretty in dev, JSON in prod
logger.addTransport({
  target: 'console',
  options: { pretty: isDev, colorize: isDev },
});

// File + HTTP only in production
if (!isDev) {
  logger.addTransport({
    target: 'file',
    options: { path: '/var/log/api/app.log', mkdir: true },
  });
  logger.addTransport({
    target: 'http',
    options: { url: process.env.LOG_INGEST_URL! },
  });
}

const log = logger.build();
```

### 7. Use `success()` for positive milestones

Signal completions, startups, and milestones clearly:

```typescript
logger.success('Database connection established');
logger.success('Migration complete');
logger.success('Server listening on port 3000');
```

### 8. Wrap risky operations in groups

Use groups for multi-step operations to visually structure console output:

```typescript
logger.group('Deployment');

try {
  logger.info('Building...');
  // ... build ...
  logger.info('Testing...');
  // ... test ...
  logger.success('Deployment successful');
} catch (err) {
  logger.error('Deployment failed', err);
} finally {
  logger.groupEnd();
}
```

***

## ❌ Don'ts

### 1. Don't log sensitive data

Never log passwords, tokens, API keys, or PII:

```typescript
// ❌ Dangerous — leaks credentials
logger.info('User login', { email: user.email, password: user.password });

// ✅ Safe — only non-sensitive fields
logger.info('User login', { userId: user.id, email: user.email });
```

### 2. Don't create a new logger instance per request

Child loggers are lightweight — they share the parent's Pino instance. Creating a new builder per request is expensive:

```typescript
// ❌ Expensive — new Pino instance per request
app.get('/users', (req, res) => {
  const logger = IgniterLogger.create()
    .withContext({ requestId: req.id })
    .build();
  logger.info('Request');
});

// ✅ Efficient — child shares Pino instance
const rootLogger = IgniterLogger.create().build();

app.get('/users', (req, res) => {
  const logger = rootLogger.child('http', { requestId: req.id });
  logger.info('Request');
});
```

### 3. Don't log in hot loops

Logging has a cost. Avoid log calls inside tight loops:

```typescript
// ❌ Bad — thousands of log lines
for (const item of largeArray) {
  logger.debug('Processing', { item });  // expensive
}

// ✅ Good — log once, summarize
logger.info('Processing batch', { count: largeArray.length });
for (const item of largeArray) {
  // process silently
}
logger.success('Batch complete', { count: largeArray.length });
```

### 4. Don't ignore flush

File and HTTP transports buffer output. Without `flush()`, the last log entries are lost on exit:

```typescript
// ❌ Lost — process exits before buffer is flushed
logger.info('Process exiting');
process.exit(0);

// ✅ Safe — flush before exit
logger.info('Process exiting');
await logger.flush();
process.exit(0);
```

### 5. Don't use `console.log` alongside the logger

Mixing `console.log` with Pino leads to inconsistent formatting and lost structured context:

```typescript
// ❌ Inconsistent — raw output mixed with pretty
console.log('Something happened');
logger.info('Something happened');

// ✅ Consistent — all through the logger
logger.info('Something happened');
```

### 6. Don't swallow errors silently

Log errors with context, not just a message:

```typescript
// ❌ Vague
try { await riskyOp(); } catch (err) {
  logger.error('Operation failed');  // where's the error?
}

// ✅ Complete
try { await riskyOp(); } catch (err) {
  logger.error('Operation failed', {
    operation: 'riskyOp',
    error: err,
  });
}
```

***

## Naming Conventions

### App Name

Use kebab-case matching your service name:

```typescript
.withAppName('payment-service')
.withAppName('user-api')
.withAppName('worker-scheduler')
```

### Component

Use a short, descriptive label for the subsystem:

```typescript
.withComponent('http')       // HTTP handling
.withComponent('database')   // Database operations
.withComponent('cache')      // Cache layer
.withComponent('auth')       // Authentication
.withComponent('stripe')     // Payment provider
```

### Child Logger Component

Children usually represent a more specific subsystem or a request scope:

```typescript
logger.child('http', { requestId })          // request-scoped
logger.child('database', { query: 'SELECT' }) // query-scoped
logger.child('tenant-id', { tenantId })       // tenant-scoped
```

***

## Performance Checklist

* [ ] Use child loggers instead of creating new instances per request
* [ ] Avoid logging inside hot loops — summarize instead
* [ ] Set appropriate log levels per environment (debug in dev, info in prod)
* [ ] Use HTTP transport `batchSize` of 50+ in production to reduce network calls
* [ ] Call `flush()` before process exit for file and HTTP transports
* [ ] Use `pretty: false` in production for faster console output (or drop console entirely)

***

## Next Steps

<Cards>
  <Card title="Framework Integration" description="Logger with Next.js, Express, Fastify, and NestJS." href="/docs/logger/framework-integration" />

  <Card title="Troubleshooting" description="Common errors and how to debug them." href="/docs/logger/troubleshooting" />

  <Card title="API Reference" description="Complete reference for every method and type." href="/docs/logger/api-reference" />
</Cards>


---

# Child Loggers

> Create scoped loggers with merged context and typed generics. Organize logs by component, request, or tenant with full TypeScript safety.
URL: https://igniterjs.com/docs/logger/child-loggers

## Child Loggers

Child loggers let you create **scoped logger instances** that inherit configuration from a parent while adding their own context. Use them to tag log entries by component, track requests, or isolate tenant data — without repeating yourself.

### Creating a Child Logger

Call `.child()` on any logger instance to create a child:

```typescript
import { IgniterLogger } from '@igniter-js/logger';

const logger = IgniterLogger.create()
  .withAppName('api')
  .withContext({ region: 'us-east-1' })
  .build();

// Child logger for HTTP request handling
const httpLogger = logger.child('http', {
  requestId: 'req-abc123',
  method: 'GET',
  path: '/users',
});

httpLogger.info('Request received');
// Component=http, region=us-east-1, requestId=req-abc123, method=GET, path=/users
```

### Method Signature

```typescript
child(
  componentName: string,
  context?: Record<string, unknown> | string,
): IIgniterLoggerManager
```

| Parameter       | Type                                | Description                                                                                                                 |
| --------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `componentName` | `string`                            | Component name for the child logger. Sets the `component` field in log entries and overrides the parent's component if set. |
| `context`       | `Record<string, unknown> \| string` | Context merged into child log entries. If a string is passed, it's wrapped as `{ label: value }`.                           |

### Context Merging

Child loggers merge context from three sources:

```
Parent builder context (withContext)
    └── Parent component
        └── Child component (overrides parent component)
            └── Child context (merged on top)
```

```typescript
const logger = IgniterLogger.create()
  .withAppName('api')
  .withContext({ region: 'us-east', version: '1.0' })
  .build();

const dbLogger = logger.child('database', {
  connection: 'main',
  query: 'SELECT',
});

dbLogger.info('Query executed', { duration: 45 });
// Final context: {
//   appName: 'api',
//   component: 'database',       ← child overrides
//   region: 'us-east',           ← inherited from parent
//   version: '1.0',              ← inherited from parent
//   connection: 'main',          ← from child context
//   query: 'SELECT',             ← from child context
//   duration: 45                 ← from per-call context
// }
```

***

## Typed Scopes

Use `.defineScopes<T>()` to enforce typed context on child loggers:

```typescript
import { IgniterLogger } from '@igniter-js/logger';

// Define the expected shape for child logger context
const logger = IgniterLogger.create()
  .withAppName('api')
  .defineScopes<{
    tenantId: string;
    userId?: string;
  }>()
  .build();

// ✅ TypeScript enforces tenantId
const tenantLogger = logger.child('tenant', {
  tenantId: 't-456',
  userId: 'u-789',
});

// ❌ TypeScript error: missing 'tenantId'
// const badLogger = logger.child('tenant', { userId: 'u-789' });
```

<Callout type="info">
  `defineScopes<T>()` changes the generic parameter on the builder, which flows into the manager's `child()` signature. Child logger context parameters become **required or optional** based on the scope type.
</Callout>

***

## Real-World Patterns

### Request-Scoped Loggers

Create a child logger for each incoming HTTP request:

```typescript
import { IgniterLogger } from '@igniter-js/logger';

const logger = IgniterLogger.create()
  .withAppName('api')
  .withContext({ region: 'us-east-1' })
  .build();

// In your request handler
function handleRequest(req: Request) {
  const requestLogger = logger.child('http', {
    requestId: crypto.randomUUID(),
    method: req.method,
    path: new URL(req.url).pathname,
  });

  requestLogger.info('Handling request');

  // Pass the child logger to downstream handlers
  const user = await fetchUser(requestLogger, req.params.id);
  requestLogger.info('User fetched', { userId: user.id });

  requestLogger.success('Request completed');
}
```

Every log entry from this handler carries `requestId`, `method`, and `path` — traceable end-to-end.

### Multi-Tenant Logging

Create a child logger per tenant with mandatory tenant context:

```typescript
const logger = IgniterLogger.create()
  .withAppName('saas-api')
  .defineScopes<{ tenantId: string }>()
  .build();

function getTenantLogger(tenantId: string) {
  return logger.child(tenantId, { tenantId });
}

// Use in your service layer
const acmeLogger = getTenantLogger('acme-corp');
acmeLogger.info('Tenant operation', { action: 'create-user' });
// Component=acme-corp, tenantId=acme-corp, action=create-user
```

### Hierarchical Service Logging

Build a tree of loggers mirroring your service architecture:

```typescript
const rootLogger = IgniterLogger.create()
  .withAppName('api')
  .withContext({ version: '2.0' })
  .build();

const httpLogger = rootLogger.child('http');
const authLogger = httpLogger.child('auth', { provider: 'oauth' });
const dbLogger = rootLogger.child('database', { pool: 'main' });
const cacheLogger = rootLogger.child('cache', { backend: 'redis' });

// Each logger carries its own component and context,
// all inheriting version=2.0 from rootLogger
authLogger.info('User authenticated', { userId: 'u-123' });
dbLogger.debug('Query executed', { query: 'SELECT', duration: 12 });
cacheLogger.info('Cache hit', { key: 'users:u-123' });
```

***

## Child vs New Instance

| Approach                              | When to Use                                                                                                          |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Child logger** (`.child()`)         | Same configuration, different component/context. Shares the Pino instance with the parent.                           |
| **New builder** (`.create().build()`) | Completely different configuration — different transports, app name, or level. Creates an independent Pino instance. |

```typescript
// Child: inherits parent config, adds context
const childLogger = parentLogger.child('worker', { jobId: 'j-42' });

// New instance: independent configuration
const workerLogger = IgniterLogger.create()
  .withAppName('worker')
  .withLevel(IgniterLogLevel.Debug)
  .addTransport({ target: 'file', options: { path: './logs/worker.log' } })
  .build();
```

<Callout type="warn">
  Child loggers share the parent's **Pino instance and transport configuration**. You cannot change transports or the log level on a child. For independent configuration, create a new logger.
</Callout>

***

## Next Steps

<Cards>
  <Card title="Advanced" description="Runtime level changes, groups, separators, flush, and error handling." href="/docs/logger/advanced" />

  <Card title="API Reference" description="Complete reference for child(), defineScopes(), and the manager interface." href="/docs/logger/api-reference" />

  <Card title="Framework Integration" description="Request-scoped loggers with Express middleware, Next.js, and Fastify." href="/docs/logger/framework-integration" />
</Cards>


---

# Framework Integration

> Integrate @igniter-js/logger with Next.js, Express, Fastify, and NestJS. Request-scoped logging, middleware patterns, and production-ready examples.
URL: https://igniterjs.com/docs/logger/framework-integration

## Framework Integration

Logger integrates with any Node.js framework. These patterns cover the most common use cases — request-scoped logging, middleware, and graceful shutdown.

***

## Express

### Basic Setup

```typescript
import express from 'express';
import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

const logger = IgniterLogger.create()
  .withAppName('express-api')
  .withLevel(IgniterLogLevel.Info)
  .build();

const app = express();

app.listen(3000, () => {
  logger.success('Server listening on port 3000');
});
```

### Request Logging Middleware

Create a child logger per request with `requestId` and route info:

```typescript
import { randomUUID } from 'crypto';
import type { Request, Response, NextFunction } from 'express';

// Attach logger to request object
declare global {
  namespace Express {
    interface Request {
      logger: ReturnType<typeof IgniterLogger.create>;
    }
  }
}

function requestLogger(req: Request, res: Response, next: NextFunction) {
  const requestId = randomUUID();

  req.logger = logger.child('http', {
    requestId,
    method: req.method,
    path: req.path,
  });

  req.logger.info('Request received');

  const start = Date.now();
  res.on('finish', () => {
    req.logger.info('Response sent', {
      statusCode: res.statusCode,
      duration: Date.now() - start,
    });
  });

  next();
}

app.use(requestLogger);

// Use it in route handlers
app.get('/users/:id', async (req, res) => {
  req.logger.debug('Fetching user', { userId: req.params.id });
  const user = await db.users.findById(req.params.id);
  req.logger.info('User fetched', { userId: user.id });
  res.json(user);
});
```

### Error Handling

```typescript
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  req.logger?.error('Unhandled error', {
    error: err.message,
    stack: err.stack,
    path: req.path,
  });
  res.status(500).json({ error: 'Internal server error' });
});
```

### Graceful Shutdown

```typescript
const server = app.listen(3000);

process.on('SIGTERM', async () => {
  logger.info('SIGTERM received — shutting down');
  server.close(async () => {
    await logger.flush();
    process.exit(0);
  });
});
```

***

## Next.js

### App Router (API Routes)

Create a shared logger module and use it in route handlers:

```typescript title="lib/logger.ts"
import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

const isDev = process.env.NODE_ENV === 'development';

export const logger = IgniterLogger.create()
  .withAppName('nextjs-app')
  .withLevel(isDev ? IgniterLogLevel.Debug : IgniterLogLevel.Info)
  .build();
```

```typescript title="app/api/users/route.ts"
import { NextRequest, NextResponse } from 'next/server';
import { logger } from '@/lib/logger';

export async function GET(request: NextRequest) {
  const requestId = crypto.randomUUID();
  const reqLogger = logger.child('http', {
    requestId,
    method: 'GET',
    path: '/api/users',
  });

  reqLogger.info('Fetching users');

  const users = await fetchUsers();

  reqLogger.info('Users fetched', { count: users.length });

  return NextResponse.json(users);
}
```

### Middleware

```typescript title="middleware.ts"
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Logger is server-side only — use in API routes, not middleware directly
  // Consider logging via HTTP transport for edge/middleware contexts
  return NextResponse.next();
}
```

<Callout type="info">
  Logger works in **server-side contexts** — API routes, Server Actions, `getServerSideProps`. It does not work in Edge Runtime or browser components. For Edge logging, use the HTTP transport and call the endpoint from your edge function.
</Callout>

### Server Actions

```typescript title="app/actions.ts"
'use server';

import { logger } from '@/lib/logger';

export async function createUser(formData: FormData) {
  const actionLogger = logger.child('action', { action: 'createUser' });

  actionLogger.info('Creating user', { email: formData.get('email') });

  const user = await db.user.create({
    data: { email: formData.get('email') as string },
  });

  actionLogger.success('User created', { userId: user.id });
}
```

### Graceful Shutdown (Next.js)

Next.js doesn't expose a direct shutdown hook. Use a custom server or register process handlers:

```typescript title="instrumentation.ts"
import { logger } from '@/lib/logger';

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    process.on('SIGTERM', async () => {
      await logger.flush();
    });

    process.on('SIGINT', async () => {
      await logger.flush();
    });
  }
}
```

***

## Fastify

### Plugin Pattern

Fastify's plugin system works naturally with Logger:

```typescript
import Fastify from 'fastify';
import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

const logger = IgniterLogger.create()
  .withAppName('fastify-api')
  .withLevel(IgniterLogLevel.Info)
  .build();

const fastify = Fastify({
  logger: false, // We use our own logger
});

// Decorate fastify instance with our logger
fastify.decorate('appLogger', logger);

// Request-scoped logger hook
fastify.addHook('onRequest', async (request, reply) => {
  const requestId = crypto.randomUUID();

  (request as any).reqLogger = logger.child('http', {
    requestId,
    method: request.method,
    url: request.url,
  });
});

fastify.addHook('onResponse', async (request, reply) => {
  const reqLogger = (request as any).reqLogger;
  reqLogger?.info('Response sent', {
    statusCode: reply.statusCode,
    duration: reply.elapsedTime,
  });
});

// Routes
fastify.get('/users', async (request, reply) => {
  const reqLogger = (request as any).reqLogger;
  reqLogger?.info('Fetching users');
  return [{ id: 1, name: 'Alice' }];
});

// Start
fastify.listen({ port: 3000 }, (err, address) => {
  if (err) {
    logger.fatal('Failed to start', err);
    process.exit(1);
  }
  logger.success(`Server listening at ${address}`);
});
```

### Graceful Shutdown

```typescript
const signals = ['SIGTERM', 'SIGINT'] as const;

for (const signal of signals) {
  process.on(signal, async () => {
    logger.info(`${signal} received — shutting down`);
    await fastify.close();
    await logger.flush();
    process.exit(0);
  });
}
```

***

## NestJS

### Custom Logger Service

Implement NestJS's `LoggerService` interface:

```typescript title="logger.service.ts"
import { Injectable, LoggerService } from '@nestjs/common';
import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

@Injectable()
export class IgniterLoggerService implements LoggerService {
  private logger = IgniterLogger.create()
    .withAppName('nestjs-app')
    .withLevel(IgniterLogLevel.Info)
    .build();

  log(message: string, context?: string) {
    this.logger.info(message, { nestContext: context });
  }

  error(message: string, trace?: string, context?: string) {
    this.logger.error(message, { nestContext: context, trace });
  }

  warn(message: string, context?: string) {
    this.logger.warn(message, { nestContext: context });
  }

  debug(message: string, context?: string) {
    this.logger.debug(message, { nestContext: context });
  }

  verbose(message: string, context?: string) {
    this.logger.trace(message, { nestContext: context });
  }

  // Direct access for structured logging
  getLogger() {
    return this.logger;
  }

  async flush() {
    await this.logger.flush();
  }
}
```

### Register in App Module

```typescript title="app.module.ts"
import { Module } from '@nestjs/common';
import { IgniterLoggerService } from './logger.service';

@Module({
  providers: [IgniterLoggerService],
  exports: [IgniterLoggerService],
})
export class AppModule {}
```

### Use in Main

```typescript title="main.ts"
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { IgniterLoggerService } from './logger.service';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    bufferLogs: true,
  });

  const logger = app.get(IgniterLoggerService);
  app.useLogger(logger);

  await app.listen(3000);
  logger.getLogger().success('NestJS app listening on port 3000');
}

bootstrap();
```

### Request-Scoped Logging (Interceptor)

```typescript title="logging.interceptor.ts"
import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
} from '@nestjs/common';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';
import { IgniterLoggerService } from './logger.service';

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  constructor(private loggerService: IgniterLoggerService) {}

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const logger = this.loggerService.getLogger();

    const reqLogger = logger.child('http', {
      requestId: crypto.randomUUID(),
      method: request.method,
      path: request.url,
    });

    reqLogger.info('Request received');

    const start = Date.now();

    return next.handle().pipe(
      tap(() => {
        reqLogger.info('Response sent', {
          duration: Date.now() - start,
        });
      }),
    );
  }
}
```

### Graceful Shutdown

```typescript title="main.ts"
import { IgniterLoggerService } from './logger.service';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const logger = app.get(IgniterLoggerService);

  // Graceful shutdown
  process.on('SIGTERM', async () => {
    logger.getLogger().info('SIGTERM received — shutting down');
    await app.close();
    await logger.flush();
    process.exit(0);
  });

  await app.listen(3000);
}
```

***

## Common Patterns Across Frameworks

### Environment-Based Configuration

```typescript title="lib/logger.ts"
import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

const isDev = process.env.NODE_ENV === 'development';
const isTest = process.env.NODE_ENV === 'test';

export function createLogger(appName: string) {
  const builder = IgniterLogger.create()
    .withAppName(appName)
    .withLevel(isTest ? IgniterLogLevel.Fatal : isDev ? IgniterLogLevel.Debug : IgniterLogLevel.Info)
    .withContext({ env: process.env.NODE_ENV, version: process.env.APP_VERSION });

  builder.addTransport({
    target: 'console',
    options: { pretty: isDev, colorize: isDev },
  });

  if (!isDev && !isTest) {
    builder.addTransport({
      target: 'http',
      options: {
        url: process.env.LOG_INGEST_URL!,
        headers: { 'X-API-Key': process.env.LOG_API_KEY! },
        batchSize: 50,
      },
    });
  }

  return builder.build();
}
```

### Testing

In tests, use a console-only logger with a high threshold:

```typescript title="test/setup.ts"
import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

export const testLogger = IgniterLogger.create()
  .withLevel(IgniterLogLevel.Fatal)  // suppress all but fatal in tests
  .addTransport({ target: 'console', options: { pretty: false } })
  .build();
```

***

## Next Steps

<Cards>
  <Card title="Best Practices" description="Production logging patterns and anti-patterns to avoid." href="/docs/logger/best-practices" />

  <Card title="Troubleshooting" description="Common errors and how to debug them." href="/docs/logger/troubleshooting" />

  <Card title="API Reference" description="Complete reference for every method and type." href="/docs/logger/api-reference" />
</Cards>


---

# Introduction

> Pino-powered structured logging for Igniter.js. Builder-pattern configuration, multi-transport support, child loggers, and full TypeScript inference — zero boilerplate.
URL: https://igniterjs.com/docs/logger

## Overview

`@igniter-js/logger` is a **Pino-backed structured logger** with a builder-pattern API. It wraps Pino's raw performance in a clean, TypeScript-first interface that feels at home in the Igniter.js ecosystem.

You configure a logger once with the builder — log level, app name, component, context, and transports — and get a fully typed manager. No Pino configuration files. No JSON. Just a fluent chain that TypeScript understands.

<Callout type="info">
  Logger delegates internally to **Pino v9** — the fastest Node.js logger. You get Pino's performance and ecosystem (pino-pretty, pino/file, external transports) behind a clean Igniter.js API.
</Callout>

### Key Features

* **Builder Pattern** — `.create().withLevel().addTransport().build()` — chained configuration with full TypeScript inference
* **Six Log Levels** — `fatal`, `error`, `warn`, `info`, `debug`, `trace` — plus `success` for positive outcomes
* **Three Built-in Transports** — console (pino-pretty), file (with rotation), HTTP (async batch delivery)
* **External Transports** — use any pino-compatible transport (Logtail, Datadog, Loki, etc.)
* **Child Loggers** — create scoped loggers with merged context for services, requests, or tenants
* **Typed Scopes** — `defineScopes<T>()` gives child loggers typed context parameters
* **Structured Context** — merge default context into every log entry; add per-call context inline
* **Visual Hierarchy** — `group()`/`groupEnd()` indent log output; `separator()` draws dividers
* **Runtime Control** — change log level, app name, or component at runtime without recreating the logger
* **Non-blocking HTTP** — async batching transport with periodic flush and automatic retry

***

## Architecture

Logger follows the **Igniter.js builder pattern**: a chainable builder produces an immutable manager. The manager wraps a Pino instance, which handles transport resolution and output.

```
┌─────────────────────────┐
│  IgniterLoggerBuilder   │  ← Chainable configuration
│  .withLevel()           │
│  .withAppName()         │
│  .withComponent()       │
│  .withContext()         │
│  .addTransport() × N    │
│  .defineScopes<T>()     │
│  .build()               │
└───────────┬─────────────┘
            │ produces
┌───────────▼─────────────┐
│ IgniterLoggerManager    │  ← Immutable, fully typed
│  .info(msg)             │
│  .error(msg, err)       │
│  .child(name, ctx)      │
│  .group() / .groupEnd() │
│  .separator()           │
│  .setLevel()            │
│  .flush()               │
└───────────┬─────────────┘
            │ delegates to
┌───────────▼─────────────┐
│       Pino v9           │  ← Raw logging engine
│  ┌──────┐ ┌──────┐      │
│  │console│ │ file │ ...  │  ← Transport targets
│  └──────┘ └──────┘      │
└─────────────────────────┘
```

### Transport Resolution

When you call `.addTransport()`, the builder stores a transport configuration. At `.build()` time, each transport is resolved:

| Target         | Resolver                  | Pino Target              |
| -------------- | ------------------------- | ------------------------ |
| `"console"`    | `resolveConsoleTransport` | `pino-pretty`            |
| `"file"`       | `resolveFileTransport`    | `pino/file`              |
| `"http"`       | `resolveHttpTransport`    | Custom async HTTP worker |
| `(any string)` | Passed through as-is      | External pino transport  |

If no transports are configured, a **console transport with pretty formatting** is added automatically.

***

## Quick Start

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/logger
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/logger
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/logger
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/logger
    ```
  </Tab>
</Tabs>

```typescript
import { IgniterLogger } from '@igniter-js/logger';

const logger = IgniterLogger.create().build();

logger.info('Server started on port 3000');
logger.error('Connection failed', new Error('timeout'));
logger.success('Deployment complete');
```

That's it. One import, one builder call, and you're logging. The default setup gives you pretty console output with timestamps.

***

## Real-World Use Cases

| Scenario                 | What Logger Provides                                                                                           |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| **API Server**           | Console transport for development, file transport for audit logs, HTTP transport for centralized log ingestion |
| **Microservices**        | App name and component labels track which service produced each log; typed scopes enforce tenant context       |
| **CLI Tools**            | `success()` for positive outcomes, `group()` for indented progress, `separator()` for section breaks           |
| **Background Jobs**      | File transport with rotation for persistent job logs; `flush()` ensures logs are written before process exit   |
| **Multi-tenant SaaS**    | Parent logger with tenant-agnostic config; `.child(tenantId, { tenantId })` creates isolated log streams       |
| **Serverless Functions** | Minimal cold-start overhead; HTTP transport ships logs to external aggregator before function terminates       |

***

## Next Steps

<Cards>
  <Card title="Installation" description="Set up logger in your project — runtime requirements and TypeScript config." href="/docs/logger/installation" />

  <Card title="Quick Start" description="Create your first logger with custom level, app name, and transports in 2 minutes." href="/docs/logger/quick-start" />

  <Card title="Transports" description="Console, file, HTTP, and external transports — with multi-transport examples." href="/docs/logger/transports" />

  <Card title="API Reference" description="Complete reference for the builder, manager, types, and error classes." href="/docs/logger/api-reference" />
</Cards>


---

# Installation

> Install and configure @igniter-js/logger. Runtime requirements, peer dependencies, and verifying your setup in under a minute.
URL: https://igniterjs.com/docs/logger/installation

## Installation

`@igniter-js/logger` works on **Node.js 18+** and **Bun 1.0+**. It bundles Pino v9 and its companion packages (`pino-pretty`, `pino-abstract-transport`) as direct dependencies — no extra installs needed for the built-in transports.

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/logger
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/logger
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/logger
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/logger
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **No peer dependencies required.** Pino, pino-pretty, and pino-abstract-transport are bundled as direct dependencies. You only need `@igniter-js/logger`.
</Callout>

***

## Runtime Requirements

### Node.js

```json title="package.json"
{
  "engines": {
    "node": ">=18.0.0"
  }
}
```

Logger uses `pino` and `pino-pretty` internally. The **console transport** (default) works out of the box. The **file transport** relies on `node:fs`. The **HTTP transport** uses the global `fetch` API (available in Node.js 18+).

### Bun

```json title="package.json"
{
  "engines": {
    "bun": ">=1.0.0"
  }
}
```

All transports work in Bun. The HTTP transport uses Bun's built-in `fetch`. The file transport uses Bun's native filesystem APIs via Pino.

<Callout type="warn">
  **Browser support:** Logger exports a **shim** for browser environments (`browser` field in `package.json`). The shim is a no-op — browser logging is not supported. Use the logger only in server-side runtimes.
</Callout>

***

## TypeScript Configuration

Logger requires TypeScript 5.0+ for the builder generic inference (`defineScopes<T>()`). Ensure your `tsconfig.json` includes:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": "ES2022"
  }
}
```

The `"bundler"` module resolution lets TypeScript resolve `@igniter-js/logger` exports correctly from both ESM and CJS consumers.

***

## Dependencies

Logger ships with three direct dependencies:

| Package                   | Purpose                      | Version |
| ------------------------- | ---------------------------- | ------- |
| `pino`                    | Core logging engine          | ^9.0.0  |
| `pino-pretty`             | Console pretty-printing      | ^13.0.0 |
| `pino-abstract-transport` | Custom HTTP transport worker | ^2.0.0  |

For **external transports** (Logtail, Datadog, Loki, etc.), install the corresponding package separately:

```bash
npm install @logtail/pino
# or
npm install pino-datadog-transport
```

***

## Verifying Installation

Create a minimal script to confirm everything works:

```typescript title="verify.ts"
import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

// Console transport (default)
const logger = IgniterLogger.create()
  .withLevel(IgniterLogLevel.Info)
  .withAppName('verify')
  .build();

logger.info('Logger is working');
logger.success('Installation verified');

// Flush and check
await logger.flush();
console.log('✅ @igniter-js/logger installed correctly');
```

Run it:

```bash
npx tsx verify.ts
```

You should see pretty-formatted log output with timestamps and a `✅` success message.

***

## Version Compatibility

| Logger Version | Pino | Node.js | Bun  |
| -------------- | ---- | ------- | ---- |
| 0.1.x          | 9.x  | 18+     | 1.0+ |

***

## Next Steps

<Cards>
  <Card title="Quick Start" description="Create your first logger with custom configuration in 2 minutes." href="/docs/logger/quick-start" />

  <Card title="Transports" description="Configure console, file, HTTP, and external transport targets." href="/docs/logger/transports" />

  <Card title="API Reference" description="Complete reference for every builder method and manager operation." href="/docs/logger/api-reference" />
</Cards>


---

# Quick Start

> Create a fully configured logger in 2 minutes. Build with context, transports, and typed scopes — copy-paste ready.
URL: https://igniterjs.com/docs/logger/quick-start

## Quick Start

This guide walks you from zero to a production-ready logger in under two minutes. You'll configure log levels, structured context, multiple transports, and child loggers — all with full TypeScript inference.

<Steps>
  <Step>
    ### Install

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        npm install @igniter-js/logger
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @igniter-js/logger
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @igniter-js/logger
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @igniter-js/logger
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Create a Basic Logger

    The simplest possible logger — one import, one line, and you're logging:

    ```typescript
    import { IgniterLogger } from '@igniter-js/logger';

    const logger = IgniterLogger.create().build();

    logger.info('Server started');
    // Output (pretty): [12:34:56] INFO: Server started
    ```

    <Callout type="info">
      When no transports are configured, a **console transport with pretty formatting** is added automatically. You get colored output and timestamps out of the box.
    </Callout>
  </Step>

  <Step>
    ### Configure Level and Context

    Set a minimum log level and merge default context into every entry:

    ```typescript
    import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

    const logger = IgniterLogger.create()
      .withLevel(IgniterLogLevel.Info)       // ignore debug/trace
      .withAppName('api')                     // appear in every log
      .withComponent('http')                  // identify this component
      .withContext({                          // merged into all entries
        region: 'us-east-1',
        version: '2.4.0',
      })
      .build();

    logger.info('Request received', { method: 'GET', path: '/users' });
    // Output includes: appName=api, component=http, region=us-east-1, method=GET, path=/users
    ```

    Messages below `Info` are silently dropped. Context from `withContext()` is merged as base keys; per-call context (`{ method, path }`) is merged on top.
  </Step>

  <Step>
    ### Add Transports

    Send logs to console, a file, and a remote HTTP endpoint — all at once:

    ```typescript
    import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

    const logger = IgniterLogger.create()
      .withLevel(IgniterLogLevel.Debug)
      .withAppName('api')
      .addTransport({
        target: 'console',
        options: { pretty: true, colorize: true },
      })
      .addTransport({
        target: 'file',
        options: {
          path: './logs/app.log',
          mkdir: true,
          rotation: { maxSizeBytes: 10 * 1024 * 1024 }, // 10 MB
        },
      })
      .addTransport({
        target: 'http',
        options: {
          url: 'https://logs.example.com/ingest',
          headers: { 'X-API-Key': process.env.LOG_API_KEY! },
          batchSize: 50,
        },
      })
      .build();

    logger.info('Multi-transport log');
    // → console (pretty), file (app.log), and HTTP (batched) — simultaneously
    ```

    Each log call writes to **all configured transports** in parallel.
  </Step>

  <Step>
    ### Create Child Loggers

    Create scoped loggers for different parts of your application:

    ```typescript
    // Parent logger with base context
    const logger = IgniterLogger.create()
      .withAppName('api')
      .withContext({ service: 'users' })
      .build();

    // Child for HTTP request handling
    const requestLogger = logger.child('http', {
      requestId: crypto.randomUUID(),
      method: 'POST',
    });

    requestLogger.info('Processing request');
    // Component=http, service=users, requestId=..., method=POST

    // Child for database operations
    const dbLogger = logger.child('database', { query: 'SELECT' });

    dbLogger.debug('Query executed', { duration: 45 });
    // Component=database, service=users, query=SELECT, duration=45
    ```

    Child loggers inherit the parent's configuration and pino instance. Context is merged — children add keys on top of the parent's defaults.
  </Step>

  <Step>
    ### Add Visual Structure

    Use groups and separators to make log output scannable:

    ```typescript
    logger.separator();
    // ──────────────────────────────────────────────────

    logger.group('User Import');
    logger.info('Reading CSV file...');
    logger.info('Parsing 1,423 records...');
    logger.success('Import complete');
    logger.groupEnd();
    //   Reading CSV file...
    //   Parsing 1,423 records...
    //   ✓ Import complete

    logger.group('Email Dispatch');
    logger.info('Sending welcome emails...');
    logger.warn('3 emails bounced');
    logger.groupEnd();
    //   Sending welcome emails...
    //   3 emails bounced
    ```

    <Callout type="info">
      Groups and separators only affect **console output**. File and HTTP transports receive the raw log lines without indentation.
    </Callout>
  </Step>

  <Step>
    ### Flush Before Exit

    For file and HTTP transports, flush buffered logs before the process exits:

    ```typescript
    import { IgniterLogger } from '@igniter-js/logger';

    const logger = IgniterLogger.create()
      .addTransport({ target: 'file', options: { path: './logs/app.log' } })
      .addTransport({ target: 'http', options: { url: 'https://logs.example.com/ingest' } })
      .build();

    // Graceful shutdown
    process.on('SIGTERM', async () => {
      logger.info('Shutting down...');
      await logger.flush();
      process.exit(0);
    });

    process.on('beforeExit', async () => {
      await logger.flush();
    });
    ```
  </Step>
</Steps>

***

## ✅ Success Checkpoint

You now have a logger that:

* Respects the configured **log level** (drops messages below the threshold)
* Merges **default context** (app name, component, region) into every entry
* Writes to **console, file, and HTTP** simultaneously
* Supports **child loggers** with scoped context
* Uses **visual formatting** (groups, separators) for readable console output
* **Flushes** buffered logs on graceful shutdown

***

## Next Steps

<Cards>
  <Card title="Transports" description="Deep dive into every transport target, options, and multi-transport patterns." href="/docs/logger/transports" />

  <Card title="Child Loggers" description="Typed scopes, context merging, and hierarchical logger patterns." href="/docs/logger/child-loggers" />

  <Card title="Advanced" description="Runtime level changes, groups, separators, flush, and error handling." href="/docs/logger/advanced" />
</Cards>


---

# Transports

> Configure where logs go — console, file, HTTP, and external pino transports. Multi-transport patterns and all options documented.
URL: https://igniterjs.com/docs/logger/transports

## Transports

Transports determine **where your log entries are written**. Logger ships with three built-in transports and supports any external pino-compatible transport. You can configure multiple transports — each log call writes to all of them simultaneously.

### Transport Architecture

Every transport is resolved at `.build()` time. The builder stores transport configurations; the manager passes them to Pino, which handles the actual output.

```
.addTransport({ target: 'console', options: {...} })
.addTransport({ target: 'file',    options: {...} })
.addTransport({ target: 'http',    options: {...} })
.addTransport({ target: '@logtail/pino', options: {...} })
                    │
                    ▼
              .build()
                    │
    ┌───────────────┼───────────────┐
    ▼               ▼               ▼
┌───────┐     ┌────────┐     ┌────────┐
│console│     │  file  │     │  http  │   ...
└───────┘     └────────┘     └────────┘
```

<Callout type="info">
  If **no transports** are configured, a console transport with pretty formatting is added automatically. You always get output somewhere.
</Callout>

***

## Console Transport

The console transport uses `pino-pretty` under the hood. It's the default when no transports are specified.

```typescript
import { IgniterLogger } from '@igniter-js/logger';

const logger = IgniterLogger.create()
  .addTransport({
    target: 'console',
    options: {
      pretty: true,
      colorize: true,
      translateTime: 'SYS:HH:MM:ss',
    },
  })
  .build();

logger.info('Pretty output with colors and timestamps');
```

### Console Options

| Option          | Type                             | Default          | Description                                                                              |
| --------------- | -------------------------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `pretty`        | `boolean`                        | `true`           | Enable pretty-printing. Set to `false` for raw JSON output (useful for log aggregators). |
| `colorize`      | `boolean`                        | `true`           | Enable ANSI color output. Turn off in CI environments or when piping output.             |
| `translateTime` | `string \| boolean`              | `"SYS:standard"` | Time format. Use `"SYS:HH:MM:ss"` for 24h, `false` to disable timestamps.                |
| `destination`   | `"stdout" \| "stderr" \| string` | `"stdout"`       | Output stream. Use `"stderr"` for errors-only output.                                    |

### Examples

<Tabs items={['Pretty (default)', 'Raw JSON', 'No color']}>
  <Tab value="Pretty (default)">
    ```typescript
    const logger = IgniterLogger.create()
      .addTransport({ target: 'console' })
      .build();

    // [12:34:56] INFO: Server started on port 3000
    ```
  </Tab>

  <Tab value="Raw JSON">
    ```typescript
    const logger = IgniterLogger.create()
      .addTransport({
        target: 'console',
        options: { pretty: false },
      })
      .build();

    // {"level":30,"time":"2026-06-02T12:34:56.789Z","msg":"Server started"}
    ```
  </Tab>

  <Tab value="No color">
    ```typescript
    const logger = IgniterLogger.create()
      .addTransport({
        target: 'console',
        options: { colorize: false },
      })
      .build();

    // Plain text output — ideal for CI logs
    ```
  </Tab>
</Tabs>

***

## File Transport

The file transport writes logs to disk using Pino's built-in `pino/file` target. It supports automatic directory creation and log rotation.

```typescript
import { IgniterLogger } from '@igniter-js/logger';

const logger = IgniterLogger.create()
  .addTransport({
    target: 'file',
    options: {
      path: './logs/app.log',
      mkdir: true,
      rotation: {
        maxSizeBytes: 10 * 1024 * 1024, // 10 MB
        maxFiles: 5,
      },
    },
  })
  .build();

logger.info('Written to file');
```

### File Options

| Option     | Type                                             | Default      | Description                                                                      |
| ---------- | ------------------------------------------------ | ------------ | -------------------------------------------------------------------------------- |
| `path`     | `string`                                         | **required** | Destination file path. Absolute or relative to `cwd`.                            |
| `mkdir`    | `boolean`                                        | `true`       | Create parent directories if they don't exist.                                   |
| `rotation` | `boolean \| IgniterFileTransportRotationOptions` | `false`      | Enable log rotation. Pass `true` for defaults, or an object for custom settings. |

### Rotation Options

When `rotation` is enabled (object form):

| Option         | Type     | Default | Description                                |
| -------------- | -------- | ------- | ------------------------------------------ |
| `maxSizeBytes` | `number` | —       | Maximum file size before rotation.         |
| `maxFiles`     | `number` | —       | Maximum number of rotated files to retain. |
| `intervalMs`   | `number` | —       | Rotation interval in milliseconds.         |

<Callout type="warn">
  Rotation behavior depends on Pino's transport worker. For advanced rotation (compression, custom naming), consider using `pino-roll` as an **external transport**.
</Callout>

### Example: Production File Logging

```typescript
import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

const logger = IgniterLogger.create()
  .withLevel(IgniterLogLevel.Info)
  .withAppName('api')
  .addTransport({
    target: 'file',
    options: {
      path: '/var/log/myapp/app.log',
      mkdir: true,
      rotation: {
        maxSizeBytes: 50 * 1024 * 1024, // 50 MB
        maxFiles: 10,
      },
    },
  })
  .build();

// Flush before graceful shutdown
process.on('SIGTERM', async () => {
  logger.info('Shutting down');
  await logger.flush();
  process.exit(0);
});
```

***

## HTTP Transport

The HTTP transport sends logs to a remote endpoint asynchronously. It **buffers and batches** log entries to avoid blocking your application.

```typescript
import { IgniterLogger } from '@igniter-js/logger';

const logger = IgniterLogger.create()
  .addTransport({
    target: 'http',
    options: {
      url: 'https://logs.example.com/ingest',
      headers: {
        'X-API-Key': process.env.LOG_API_KEY!,
        'X-Service': 'api',
      },
      batchSize: 100,
      timeoutMs: 5000,
      flushInterval: 5000,
    },
  })
  .build();

logger.info('Sent to remote log aggregator');
```

### How It Works

1. Each log call pushes an entry into an **in-memory buffer** (async, non-blocking).
2. When the buffer reaches `batchSize`, or every `flushInterval` ms, entries are sent as a single HTTP POST.
3. If the request fails (network error or non-2xx), entries are **put back in the buffer** — logs are never lost due to transient failures.
4. On transport close (process exit), remaining logs are flushed.

<Callout type="info">
  The HTTP transport uses a **custom Pino transport worker** (`http-pino-transport.ts`) that runs in a separate thread. Your application's event loop is never blocked by log delivery.
</Callout>

### HTTP Options

| Option          | Type                     | Default      | Description                                                                 |
| --------------- | ------------------------ | ------------ | --------------------------------------------------------------------------- |
| `url`           | `string`                 | **required** | Target URL for log ingestion. Must accept POST with JSON body.              |
| `headers`       | `Record<string, string>` | `{}`         | HTTP headers for authentication or metadata (API keys, service name).       |
| `batchSize`     | `number`                 | `10`         | Number of entries per batch. Flush triggers when this threshold is reached. |
| `timeoutMs`     | `number`                 | `5000`       | Request timeout in milliseconds. Uses `AbortSignal.timeout()`.              |
| `flushInterval` | `number`                 | `5000`       | Periodic flush interval in milliseconds.                                    |

### Request Format

The HTTP transport sends a JSON POST with this structure:

```json
{
  "logs": [
    { "level": 30, "time": "2026-06-02T12:34:56.789Z", "msg": "Server started" },
    { "level": 50, "time": "2026-06-02T12:34:57.123Z", "msg": "Connection failed", "err": {...} }
  ],
  "timestamp": "2026-06-02T12:34:57.456Z"
}
```

***

## External Transports

Any **pino-compatible transport** can be used by passing its package name as the `target`:

```typescript
import { IgniterLogger } from '@igniter-js/logger';

// pino-pretty (must be installed separately)
const prettyLogger = IgniterLogger.create()
  .addTransport({
    target: 'pino-pretty',
    options: {
      colorize: true,
      translateTime: 'SYS:standard',
      ignore: 'pid,hostname',
    },
  })
  .build();

// SaaS log aggregator (e.g., Logtail)
const remoteLogger = IgniterLogger.create()
  .addTransport({
    target: '@logtail/pino',
    options: {
      sourceToken: process.env.LOGTAIL_TOKEN!,
    },
  })
  .build();
```

### Popular External Transports

| Transport                | Install                              | Use Case                                           |
| ------------------------ | ------------------------------------ | -------------------------------------------------- |
| `pino-pretty`            | `npm install pino-pretty`            | Advanced pretty-printing with custom color schemes |
| `@logtail/pino`          | `npm install @logtail/pino`          | Logtail / Better Stack log management              |
| `pino-datadog-transport` | `npm install pino-datadog-transport` | Datadog log ingestion                              |
| `pino-loki`              | `npm install pino-loki`              | Grafana Loki log aggregation                       |
| `pino-elasticsearch`     | `npm install pino-elasticsearch`     | Elasticsearch indexing                             |
| `pino-roll`              | `npm install pino-roll`              | Advanced file rotation with compression            |
| `pino-sentry-transport`  | `npm install pino-sentry-transport`  | Sentry error tracking                              |

<Callout type="info">
  External transports receive the same log entries as built-in ones. Logger does not modify the payload — Pino passes entries directly to the transport.
</Callout>

***

## Multi-Transport Patterns

### Development vs Production

Use different transport configurations based on the environment:

```typescript
import { IgniterLogger, IgniterLogLevel } from '@igniter-js/logger';

const isDev = process.env.NODE_ENV !== 'production';

const logger = IgniterLogger.create()
  .withLevel(isDev ? IgniterLogLevel.Debug : IgniterLogLevel.Info)
  .withAppName('api');

// Console always — pretty in dev, JSON in prod
logger.addTransport({
  target: 'console',
  options: { pretty: isDev, colorize: isDev },
});

// File only in production
if (!isDev) {
  logger.addTransport({
    target: 'file',
    options: { path: '/var/log/api/app.log', mkdir: true },
  });
}

// HTTP only in production
if (!isDev) {
  logger.addTransport({
    target: 'http',
    options: {
      url: process.env.LOG_INGEST_URL!,
      headers: { 'X-API-Key': process.env.LOG_API_KEY! },
    },
  });
}

const log = logger.build();

log.info(`Logger started in ${isDev ? 'development' : 'production'} mode`);
```

### Split Log Levels Across Transports

Send errors to one destination and all logs to another:

```typescript
// All logs to file, errors to Sentry
const logger = IgniterLogger.create()
  .withLevel(IgniterLogLevel.Debug)
  .withAppName('api')
  .addTransport({
    target: 'file',
    options: { path: './logs/all.log' },
  })
  .addTransport({
    target: 'pino-sentry-transport',
    options: {
      dsn: process.env.SENTRY_DSN!,
      level: 'error', // only errors and above
    },
  })
  .build();
```

***

## Next Steps

<Cards>
  <Card title="Child Loggers" description="Create scoped loggers with merged context and typed generics." href="/docs/logger/child-loggers" />

  <Card title="Advanced" description="Runtime level changes, groups, flush, and error handling patterns." href="/docs/logger/advanced" />

  <Card title="Framework Integration" description="Use logger with Next.js, Express, Fastify, and NestJS." href="/docs/logger/framework-integration" />
</Cards>


---

# Troubleshooting

> Common errors, transport failures, log level issues, and debugging strategies for @igniter-js/logger.
URL: https://igniterjs.com/docs/logger/troubleshooting

## Troubleshooting

Common issues and how to fix them when working with `@igniter-js/logger`.

***

## Debug Messages Not Appearing

**Symptom:** You call `logger.debug(...)` or `logger.trace(...)` but nothing appears in the output.

**Cause:** The log level is set higher than `Debug`. Logger filters out messages below the configured minimum level.

**Solution:** Set the level to `Debug` or `Trace`:

```typescript
// In the builder
const logger = IgniterLogger.create()
  .withLevel(IgniterLogLevel.Debug)
  .build();

// Or at runtime
logger.setLevel(IgniterLogLevel.Debug);
```

<Callout type="info">
  The default level (when not set) is `info` — which means `debug` and `trace` are suppressed by default.
</Callout>

***

## File Transport Not Writing

**Symptom:** You configured a file transport but no file is created or the file is empty.

**Causes and Solutions:**

### 1. Missing flush before exit

File transport buffers output. Without `flush()`, logs may not be written before the process exits:

```typescript
process.on('beforeExit', async () => {
  await logger.flush();
});
```

### 2. Invalid file path

Ensure the directory exists or `mkdir: true` is set:

```typescript
.addTransport({
  target: 'file',
  options: {
    path: './logs/app.log',
    mkdir: true,  // creates ./logs/ if missing
  },
})
```

### 3. Permission denied

Check write permissions on the target directory:

```bash
ls -la ./logs/
# drwxr-xr-x  ... logs/
```

### 4. Verify the file

Add a small delay after logging and flush to confirm:

```typescript
logger.info('Test message');
await logger.flush();
await new Promise(r => setTimeout(r, 100));

import { readFileSync } from 'fs';
console.log(readFileSync('./logs/app.log', 'utf-8'));
```

***

## HTTP Transport Not Sending

**Symptom:** HTTP transport is configured but logs are not reaching the remote endpoint.

**Causes and Solutions:**

### 1. Batch not yet full

By default, HTTP transport batches 10 entries before sending. Log more entries or lower the `batchSize`:

```typescript
.addTransport({
  target: 'http',
  options: {
    url: 'https://logs.example.com/ingest',
    batchSize: 1,   // send every entry immediately
    flushInterval: 1000,  // or flush every 1s
  },
})
```

### 2. Missing flush on exit

The HTTP transport uses `setInterval` with `.unref()` — it won't keep the process alive. Call `flush()` before exit:

```typescript
process.on('SIGTERM', async () => {
  await logger.flush();
  process.exit(0);
});
```

### 3. Network errors

HTTP transport silently retries on failure (puts logs back in buffer). Check your URL, headers, and network:

```typescript
// Verify the endpoint independently
fetch('https://logs.example.com/ingest', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': '...' },
  body: JSON.stringify({ logs: [], timestamp: new Date().toISOString() }),
}).then(r => console.log('Status:', r.status));
```

### 4. Firewall / CORS

If your log endpoint is behind a firewall, ensure the process has outbound access to the URL.

***

## Console Output Is Raw JSON Instead of Pretty

**Symptom:** Console output shows raw JSON like `{"level":30,"msg":"hello"}` instead of formatted text.

**Cause:** Pretty printing is disabled. This is the default when `pretty: false` or when piping output to a file.

**Solution:** Explicitly enable pretty printing:

```typescript
.addTransport({
  target: 'console',
  options: { pretty: true, colorize: true },
})
```

Or use the default (which adds console with pretty automatically if no transports are configured):

```typescript
const logger = IgniterLogger.create().build();
// Defaults to console with pretty formatting
```

***

## Duplicate Log Entries

**Symptom:** Each log message appears twice.

**Cause:** You added the console transport explicitly AND the default console transport was also added. The default is only added when **zero transports** are configured.

**Solution:** Either rely on the default (no `.addTransport()` calls) or configure all transports explicitly:

```typescript
// ❌ Duplicate: explicit console + implicit default
const logger = IgniterLogger.create()
  .addTransport({ target: 'console' })  // explicit
  .build();
// Builder sees 1 transport — no default added. This is fine.

// ✅ Explicit is fine — the default only kicks in when 0 transports exist
```

The duplicate scenario happens when you inadvertently call `.addTransport()` and expect a console default. The rule: **if any transports are configured, no default is added.**

***

## `flush()` Hangs or Times Out

**Symptom:** `await logger.flush()` never resolves.

**Cause:** The HTTP transport may be waiting on a slow endpoint. The Pino file transport may be stuck.

**Solution:** Add a timeout:

```typescript
const flushWithTimeout = async (logger: IIgniterLoggerManager, ms = 5000) => {
  await Promise.race([
    logger.flush(),
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('Flush timed out')), ms)
    ),
  ]);
};

process.on('SIGTERM', async () => {
  try {
    await flushWithTimeout(logger, 3000);
  } catch {
    console.error('Flush timed out — exiting anyway');
  }
  process.exit(0);
});
```

***

## Child Logger Doesn't Inherit Parent Context

**Symptom:** A child logger isn't picking up the parent's default context.

**Cause:** Child loggers inherit context from the **Pino base object** (set at `.build()` time), not from the builder state directly. If the parent logger was built without `.withContext()`, children won't have it.

**Solution:** Ensure parent context is configured in the builder before `.build()`:

```typescript
// ✅ Context is in the builder — child inherits it
const logger = IgniterLogger.create()
  .withContext({ service: 'api' })
  .build();

const child = logger.child('http');
child.info('Request');  // includes service=api
```

***

## TypeScript Errors with `defineScopes<T>()`

**Symptom:** TypeScript complains about missing properties on child logger context.

**Cause:** `defineScopes<T>()` makes the scope properties **required** on `child()` context.

**Solution:** Make properties optional in the type if they aren't always present:

```typescript
const logger = IgniterLogger.create()
  .defineScopes<{
    tenantId?: string;    // optional
    userId?: string;      // optional
  }>()
  .build();

// Both work now
logger.child('tenant', { tenantId: 't-1' });
logger.child('tenant', {});  // also valid
```

***

## `group()` / `groupEnd()` Mismatch

**Symptom:** Indentation is wrong — logs are permanently indented or not indented at all.

**Cause:** `group()` and `groupEnd()` calls are unbalanced — more `group()` calls than `groupEnd()` (or vice versa).

**Solution:** Ensure every `group()` has a matching `groupEnd()`:

```typescript
logger.group('Section');

try {
  // ... work ...
} finally {
  logger.groupEnd();  // always end, even on error
}
```

***

## Pino Version Conflicts

**Symptom:** `Error: Cannot find module 'pino'` or version mismatch errors.

**Cause:** Multiple Pino versions in your dependency tree.

**Solution:** Check for duplicate Pino installations:

```bash
npm ls pino
# or
pnpm why pino
```

Logger requires Pino v9 (`"pino": "^9.0.0"`). If another package depends on Pino v8, use `overrides` or `resolutions`:

```json title="package.json"
{
  "overrides": {
    "pino": "^9.0.0"
  }
}
```

***

## Next Steps

<Cards>
  <Card title="Best Practices" description="Production logging patterns, structured context conventions, and anti-patterns." href="/docs/logger/best-practices" />

  <Card title="Framework Integration" description="Logger with Next.js, Express, Fastify, and NestJS — request-scoped patterns." href="/docs/logger/framework-integration" />

  <Card title="API Reference" description="Complete reference for every method, type, and error class." href="/docs/logger/api-reference" />
</Cards>


---

# Advanced Configuration

> Learn advanced configuration options for customizing tool generation, response transformation, and adapter behavior.
URL: https://igniterjs.com/docs/mcp-server/advanced

## Overview

This guide covers advanced configuration options for fine-tuning your MCP server, including custom tool naming, filtering, transformation, response customization, and adapter-specific settings.

***

## Tool Configuration

### Custom Naming Strategy

Customize how router actions are named as MCP tools:

```typescript
// Builder Pattern
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withToolTransform((controller, action, actionConfig) => {
    // Custom naming: controller.action instead of controller_action
    return {
      name: `${controller}.${action}`,
      description: actionConfig.description || `Execute ${controller} ${action}`,
      schema: actionConfig.body || actionConfig.query || {},
    };
  })
  .build();

// Function API
const { server } = createMcpAdapter({
  router: AppRouter,
  tools: {
    naming: (controller, action) => `${controller}.${action}`,
  }
});
```

***

### Filtering Tools

Control which actions are exposed as tools:

```typescript
// Builder Pattern
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withToolTransform((controller, action, actionConfig) => {
    // Only expose actions with 'mcp-enabled' tag
    if (!actionConfig.tags?.includes('mcp-enabled')) {
      return null; // Filter out this tool
    }
    
    return {
      name: `${controller}_${action}`,
      description: actionConfig.description,
      schema: actionConfig.body || actionConfig.query || {},
    };
  })
  .build();

// Function API
const { server } = createMcpAdapter({
  router: AppRouter,
  tools: {
    filter: (controller, action, actionConfig) => {
      // Only expose public actions
      return actionConfig.tags?.includes('public') ?? false;
    }
  }
});
```

***

### Tool Transformation

Transform tool configurations before registration:

```typescript
// Builder Pattern
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withToolTransform((controller, action, actionConfig) => {
    return {
      name: `${controller}_${action}`,
      // Use summary if available, fallback to description
      description: actionConfig.summary || 
                   actionConfig.description || 
                   `Execute ${controller} ${action}`,
      schema: actionConfig.body || actionConfig.query || {},
      tags: [
        ...(actionConfig.tags || []),
        controller,
        actionConfig.method?.toLowerCase(),
      ].filter(Boolean),
    };
  })
  .build();

// Function API
const { server } = createMcpAdapter({
  router: AppRouter,
  tools: {
    transform: (controller, action, actionConfig) => {
      return {
        name: `${controller}_${action}`,
        description: actionConfig.summary || actionConfig.description,
        schema: actionConfig.body || actionConfig.query || {},
        tags: actionConfig.tags || [],
      };
    }
  }
});
```

***

### Disabling Auto-Mapping

Disable automatic mapping of router actions:

```typescript
// Function API
const { server } = createMcpAdapter({
  router: AppRouter,
  tools: {
    autoMap: false, // Only custom tools will be registered
    custom: [
      { /* custom tool 1 */ },
      { /* custom tool 2 */ },
    ]
  }
});
```

***

## Response Transformation

### Custom Response Format

Transform Igniter.js responses to MCP format:

```typescript
// Builder Pattern
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withResponse({
    transform: async (igniterResponse, toolName, context) => {
      // Customize response format
      if (igniterResponse.success) {
        return {
          content: [{
            type: 'text',
            text: JSON.stringify({
              success: true,
              data: igniterResponse.data,
              timestamp: new Date().toISOString(),
            }, null, 2)
          }]
        };
      } else {
        return {
          content: [{
            type: 'text',
            text: `Error: ${igniterResponse.error}`
          }],
          isError: true
        };
      }
    }
  })
  .build();

// Function API
const { server } = createMcpAdapter({
  router: AppRouter,
  response: {
    transform: async (igniterResponse, toolName, context) => {
      return {
        content: [{
          type: 'text',
          text: JSON.stringify(igniterResponse, null, 2)
        }]
      };
    }
  }
});
```

***

### Custom Error Handling

Handle errors with custom formatting:

```typescript
// Builder Pattern
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withResponse({
    onError: async (error, toolName, context) => {
      // Custom error formatting
      const errorInfo = {
        tool: toolName,
        error: error.message,
        type: error.constructor.name,
        timestamp: new Date().toISOString(),
      };
      
      // Log to error tracking
      await errorTracking.log(errorInfo);
      
      // Return user-friendly error
      return {
        content: [{
          type: 'text',
          text: `An error occurred while executing ${toolName}: ${error.message}`
        }],
        isError: true
      };
    }
  })
  .build();

// Function API
const { server } = createMcpAdapter({
  router: AppRouter,
  response: {
    onError: async (error, toolName, context) => {
      return {
        content: [{
          type: 'text',
          text: `Error in ${toolName}: ${error.message}`
        }],
        isError: true
      };
    }
  }
});
```

***

## Adapter Configuration

### Base Path

Configure the base path for MCP endpoints:

```typescript
// Function API
const { server } = createMcpAdapter({
  router: AppRouter,
  adapter: {
    basePath: '/api/mcp', // All MCP routes under this path
  }
});
```

***

### Max Duration

Set maximum execution duration:

```typescript
// Function API
const { server } = createMcpAdapter({
  router: AppRouter,
  adapter: {
    maxDuration: 60, // 60 seconds max execution time
  }
});
```

***

### Verbose Logging

Enable verbose logging for debugging:

```typescript
// Function API
const { server } = createMcpAdapter({
  router: AppRouter,
  adapter: {
    verboseLogs: true, // Enable detailed logging
  }
});
```

***

### Redis Configuration

Configure Redis for adapter features (if needed):

```typescript
// Function API
const { server } = createMcpAdapter({
  router: AppRouter,
  adapter: {
    redis: {
      url: process.env.REDIS_URL,
    }
  }
});
```

***

## Logger Configuration

### Custom Logger

Configure custom logging:

```typescript
// Builder Pattern
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withLogger({
    log: (message) => console.log(`[MCP] ${message}`),
    error: (message) => console.error(`[MCP ERROR] ${message}`),
    warn: (message) => console.warn(`[MCP WARN] ${message}`),
    debug: (message) => console.debug(`[MCP DEBUG] ${message}`),
  })
  .build();

// Function API with logger (if supported)
const { server } = createMcpAdapter({
  router: AppRouter,
  logger: {
    log: (message) => console.log(`[MCP] ${message}`),
    error: (message) => console.error(`[MCP ERROR] ${message}`),
    warn: (message) => console.warn(`[MCP WARN] ${message}`),
    debug: (message) => console.debug(`[MCP DEBUG] ${message}`),
  }
});
```

***

## Server Capabilities

Configure server capabilities to advertise:

```typescript
// Builder Pattern
import { ServerCapabilities } from '@modelcontextprotocol/sdk/types';

const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withCapabilities({
    tools: {
      listChanged: true, // Support tool list changes
    },
    prompts: {
      listChanged: true, // Support prompt list changes
    },
    resources: {
      subscribe: true, // Support resource subscriptions
      listChanged: true, // Support resource list changes
    },
  })
  .build();
```

***

## Complete Advanced Example

Here's a complete example combining multiple advanced features:

```typescript
import { IgniterMcpServer } from '@igniter-js/adapter-mcp-server';
import { ServerCapabilities } from '@modelcontextprotocol/sdk/types';

const { handler, auth } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withServerInfo({
    name: 'Advanced MCP Server',
    version: '1.0.0',
  })
  .withInstructions(
    "This server provides advanced tools for managing resources. " +
    "Use appropriate tools based on your needs."
  )
  .withCapabilities({
    tools: { listChanged: true },
    resources: { subscribe: true },
  })
  .withToolTransform((controller, action, actionConfig) => {
    // Only expose public actions
    if (!actionConfig.tags?.includes('public')) {
      return null;
    }
    
    // Custom naming and description
    return {
      name: `${controller}_${action}`,
      description: actionConfig.summary || actionConfig.description || `Execute ${action}`,
      schema: actionConfig.body || actionConfig.query || {},
      tags: [controller, actionConfig.method?.toLowerCase()].filter(Boolean),
    };
  })
  .withResponse({
    transform: async (igniterResponse, toolName, context) => {
      return {
        content: [{
          type: 'text',
          text: JSON.stringify(igniterResponse, null, 2)
        }]
      };
    },
    onError: async (error, toolName, context) => {
      return {
        content: [{
          type: 'text',
          text: `Error in ${toolName}: ${error.message}`
        }],
        isError: true
      };
    }
  })
  .withLogger({
    log: (message) => console.log(`[MCP] ${message}`),
    error: (message) => console.error(`[MCP ERROR] ${message}`),
    warn: (message) => console.warn(`[MCP WARN] ${message}`),
    debug: (message) => console.debug(`[MCP DEBUG] ${message}`),
  })
  .withEvents({
    onToolCall: async (toolName, args, context) => {
      console.log(`Tool called: ${toolName}`);
    },
    onToolError: async (toolName, error, context) => {
      console.error(`Tool error: ${toolName}`, error);
    }
  })
  .build();

export const GET = handler;
export const POST = handler;
```

***

## Best Practices

### 1. Consistent Naming

Use consistent naming strategies across your tools:

```typescript
// ✅ Good - Consistent format
naming: (controller, action) => `${controller}_${action}`

// ❌ Bad - Inconsistent formats
naming: (controller, action) => {
  if (controller === 'users') return `get${action}`;
  return `${controller}_${action}`;
}
```

### 2. Selective Exposure

Only expose tools that should be accessible:

```typescript
filter: (controller, action, actionConfig) => {
  // Only expose public or mcp-enabled actions
  return actionConfig.tags?.includes('public') || 
         actionConfig.tags?.includes('mcp-enabled');
}
```

### 3. Comprehensive Error Handling

Always provide user-friendly error messages:

```typescript
onError: async (error, toolName, context) => {
  return {
    content: [{
      type: 'text',
      text: `An error occurred: ${error.message}. Please try again or contact support.`
    }],
    isError: true
  };
}
```

### 4. Structured Logging

Use structured logging for better observability:

```typescript
withLogger({
  log: (message) => logger.info({ component: 'mcp', message }),
  error: (message) => logger.error({ component: 'mcp', message }),
  warn: (message) => logger.warn({ component: 'mcp', message }),
  debug: (message) => logger.debug({ component: 'mcp', message }),
})
```

***

## Next Steps

* Check out [Best Practices](/docs/mcp-server/best-practices) for production recommendations
* Learn about [Event Handlers](/docs/mcp-server/events) for monitoring
* Explore [OAuth](/docs/mcp-server/oauth) for securing your server


---

# Best Practices

> Follow these best practices to build secure, performant, and maintainable MCP servers.
URL: https://igniterjs.com/docs/mcp-server/best-practices

## Overview

This guide covers best practices for building production-ready MCP servers with the Igniter.js adapter. Follow these recommendations to ensure security, performance, and maintainability.

***

## Security

### 1. Always Use OAuth for Production

Never expose sensitive APIs without authentication:

```typescript
// ✅ Good - OAuth enabled
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withOAuth({
    issuer: process.env.OAUTH_ISSUER,
    verifyToken: async ({ bearerToken }) => {
      return await verifyJWT(bearerToken);
    }
  })
  .build();

// ❌ Bad - No authentication
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .build();
```

***

### 2. Filter Sensitive Actions

Only expose actions that should be accessible via MCP:

```typescript
// ✅ Good - Filter sensitive actions
tools: {
  filter: (controller, action, actionConfig) => {
    // Only expose public actions
    return actionConfig.tags?.includes('public') || 
           actionConfig.tags?.includes('mcp-enabled');
  }
}

// ❌ Bad - Expose everything
tools: {
  autoMap: true, // Exposes all actions including admin endpoints
}
```

***

### 3. Sanitize Inputs and Outputs

Remove sensitive data from logs and responses:

```typescript
// ✅ Good - Sanitize sensitive data
withEvents({
  onToolCall: async (toolName, args, context) => {
    const sanitized = {
      ...args,
      password: undefined,
      token: undefined,
      secret: undefined,
    };
    await logger.log(toolName, sanitized);
  }
})

// ❌ Bad - Log everything including secrets
withEvents({
  onToolCall: async (toolName, args, context) => {
    await logger.log(toolName, args); // May include passwords!
  }
})
```

***

### 4. Validate All Inputs

Use Zod schemas to validate tool arguments:

```typescript
// ✅ Good - Strict validation
addTool({
  name: 'createUser',
  args: {
    email: z.string().email(),
    password: z.string().min(8).regex(/[A-Za-z0-9@$!%*#?&]/),
  },
  handler: async (args, context) => {
    // args.email and args.password are validated
  }
})

// ❌ Bad - No validation
addTool({
  name: 'createUser',
  args: {},
  handler: async (args, context) => {
    // args could be anything!
  }
})
```

***

## Performance

### 1. Monitor Execution Times

Track tool execution performance:

```typescript
// ✅ Good - Monitor performance
withEvents({
  onToolSuccess: async (toolName, result, duration, context) => {
    await metrics.record('tool_execution', {
      tool: toolName,
      duration,
    });
    
    if (duration > 5000) {
      await alerts.warn(`Slow tool: ${toolName} took ${duration}ms`);
    }
  }
})
```

***

### 2. Use Efficient Data Formats

Return data in efficient formats:

```typescript
// ✅ Good - Structured JSON
handler: async (args, context) => {
  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        success: true,
        data: result,
      }, null, 2)
    }]
  };
}

// ❌ Bad - Verbose text
handler: async (args, context) => {
  return {
    content: [{
      type: 'text',
      text: `Success! Data: ${JSON.stringify(result)} and more text...`
    }]
  };
}
```

***

### 3. Implement Rate Limiting

Protect your server from abuse:

```typescript
// ✅ Good - Rate limiting
withEvents({
  onToolCall: async (toolName, args, context) => {
    const clientId = context.client || 'unknown';
    const limit = await rateLimiter.check(`mcp:${clientId}`, {
      limit: 100,
      window: 60000, // 1 minute
    });
    
    if (limit < 0) {
      throw new Error('Rate limit exceeded');
    }
  }
})
```

***

## Error Handling

### 1. Provide Clear Error Messages

Help users understand what went wrong:

```typescript
// ✅ Good - Clear error messages
withResponse({
  onError: async (error, toolName, context) => {
    return {
      content: [{
        type: 'text',
        text: `An error occurred while executing ${toolName}: ${error.message}. ` +
              `Please check your inputs and try again.`
      }],
      isError: true
    };
  }
})

// ❌ Bad - Generic errors
withResponse({
  onError: async (error, toolName, context) => {
    return {
      content: [{
        type: 'text',
        text: 'Error occurred'
      }],
      isError: true
    };
  }
})
```

***

### 2. Log Errors Properly

Track errors for debugging:

```typescript
// ✅ Good - Comprehensive error logging
withEvents({
  onToolError: async (toolName, error, context) => {
    await errorTracking.log({
      tool: toolName,
      error: error.message,
      stack: error.stack,
      args: sanitizeArgs(context.request.body),
      timestamp: new Date(),
    });
  }
})
```

***

### 3. Don't Expose Internal Details

Avoid exposing sensitive error details:

```typescript
// ✅ Good - Hide internal details
withResponse({
  onError: async (error, toolName, context) => {
    // Log full error internally
    await logger.error('Tool error', { tool: toolName, error });
    
    // Return user-friendly message
    return {
      content: [{
        type: 'text',
        text: `An error occurred. Please try again or contact support.`
      }],
      isError: true
    };
  }
})

// ❌ Bad - Expose stack traces
withResponse({
  onError: async (error, toolName, context) => {
    return {
      content: [{
        type: 'text',
        text: error.stack // Exposes internal structure!
      }],
      isError: true
    };
  }
})
```

***

## Tool Design

### 1. Use Descriptive Names

Make tool names clear and self-documenting:

```typescript
// ✅ Good - Descriptive names
{
  name: 'calculateTax',
  description: 'Calculate sales tax for a given amount',
}

// ❌ Bad - Unclear names
{
  name: 'tax',
  description: 'Calculate tax',
}
```

***

### 2. Provide Clear Descriptions

Help AI agents understand your tools:

```typescript
// ✅ Good - Clear descriptions
{
  name: 'processOrder',
  description: 'Process a customer order, validate payment, update inventory, and send confirmation email',
}

// ❌ Bad - Vague descriptions
{
  name: 'processOrder',
  description: 'Process order',
}
```

***

### 3. Use Zod Descriptions

Add descriptions to schema fields:

```typescript
// ✅ Good - Schema descriptions
args: {
  amount: z.number().describe('The monetary amount in USD'),
  taxRate: z.number().min(0).max(1).describe('Tax rate as decimal (0.08 = 8%)'),
}

// ❌ Bad - No descriptions
args: {
  amount: z.number(),
  taxRate: z.number(),
}
```

***

### 4. Keep Tools Focused

Each tool should do one thing well:

```typescript
// ✅ Good - Focused tools
addTool({ name: 'getUser', /* ... */ })
addTool({ name: 'updateUser', /* ... */ })
addTool({ name: 'deleteUser', /* ... */ })

// ❌ Bad - Multi-purpose tool
addTool({
  name: 'manageUser',
  // Handles get, update, delete all in one
})
```

***

## Configuration

### 1. Use Environment Variables

Store configuration in environment variables:

```typescript
// ✅ Good - Environment variables
withOAuth({
  issuer: process.env.OAUTH_ISSUER,
  verifyToken: async ({ bearerToken }) => {
    return await verifyJWT(bearerToken, process.env.JWT_SECRET);
  }
})

// ❌ Bad - Hardcoded values
withOAuth({
  issuer: 'https://auth.example.com',
  verifyToken: async ({ bearerToken }) => {
    return await verifyJWT(bearerToken, 'secret-key');
  }
})
```

***

### 2. Consistent Naming Strategy

Use consistent naming across your tools:

```typescript
// ✅ Good - Consistent format
tools: {
  naming: (controller, action) => `${controller}_${action}`,
}

// ❌ Bad - Inconsistent formats
tools: {
  naming: (controller, action) => {
    if (controller === 'users') return `get${action}`;
    return `${controller}_${action}`;
  }
}
```

***

### 3. Organize by Feature

Group related tools together:

```typescript
// ✅ Good - Organized by feature
const usersController = igniter.controller({
  path: '/users',
  actions: {
    list: igniter.query({ /* ... */ }),
    getById: igniter.query({ /* ... */ }),
    create: igniter.mutation({ /* ... */ }),
  }
});

// ❌ Bad - Everything mixed
const allController = igniter.controller({
  path: '/all',
  actions: {
    users: igniter.query({ /* ... */ }),
    products: igniter.query({ /* ... */ }),
    orders: igniter.query({ /* ... */ }),
  }
});
```

***

## Monitoring and Observability

### 1. Log All Operations

Track all MCP operations:

```typescript
// ✅ Good - Comprehensive logging
withEvents({
  onRequest: async (request, context) => {
    await logger.info('MCP request', {
      url: request.url,
      method: request.method,
      timestamp: context.timestamp,
    });
  },
  onToolCall: async (toolName, args, context) => {
    await logger.info('Tool called', {
      tool: toolName,
      args: sanitizeArgs(args),
    });
  }
})
```

***

### 2. Monitor Performance

Track execution times and success rates:

```typescript
// ✅ Good - Performance monitoring
withEvents({
  onToolSuccess: async (toolName, result, duration, context) => {
    await metrics.histogram('tool_duration', duration, {
      tool: toolName,
    });
    await metrics.increment('tool_success', {
      tool: toolName,
    });
  },
  onToolError: async (toolName, error, context) => {
    await metrics.increment('tool_error', {
      tool: toolName,
      error: error.constructor.name,
    });
  }
})
```

***

### 3. Set Up Alerts

Alert on critical issues:

```typescript
// ✅ Good - Alerting
withEvents({
  onToolError: async (toolName, error, context) => {
    if (isCriticalTool(toolName)) {
      await alerts.send({
        type: 'critical_tool_failure',
        tool: toolName,
        error: error.message,
      });
    }
  },
  onError: async (error, context) => {
    await alerts.send({
      type: 'mcp_adapter_error',
      error: error.message,
      severity: 'critical',
    });
  }
})
```

***

## Testing

### 1. Test Tool Handlers

Write unit tests for your tools:

```typescript
// ✅ Good - Tested handlers
describe('calculateTax tool', () => {
  it('calculates tax correctly', async () => {
    const result = await tool.handler({
      amount: 100,
      taxRate: 0.08,
    }, mockContext);
    
    expect(result.content[0].text).toContain('8.00');
  });
});
```

***

### 2. Test Error Cases

Test error handling:

```typescript
// ✅ Good - Error testing
describe('calculateTax tool', () => {
  it('handles invalid inputs', async () => {
    await expect(
      tool.handler({ amount: -100, taxRate: 0.08 }, mockContext)
    ).rejects.toThrow();
  });
});
```

***

## Documentation

### 1. Document Your Tools

Provide clear documentation:

```typescript
// ✅ Good - Well documented
addTool({
  name: 'calculateTax',
  description: 'Calculate sales tax for a given amount. ' +
               'The tax rate should be provided as a decimal (e.g., 0.08 for 8%). ' +
               'Returns the calculated tax amount and total.',
  args: {
    amount: z.number().positive().describe('The amount to calculate tax for in USD'),
    taxRate: z.number().min(0).max(1).describe('Tax rate as decimal (0.08 = 8%)'),
  },
  // ...
})
```

***

### 2. Keep Instructions Updated

Update instructions as your API evolves:

```typescript
// ✅ Good - Updated instructions
withInstructions(
  "This server provides tools for managing users, products, and orders. " +
  "Use users.list to get all users, users.create to add new users, " +
  "products.search to find products, and orders.process to process orders."
)
```

***

## Summary

Follow these best practices to build secure, performant, and maintainable MCP servers:

* ✅ Always use OAuth for production
* ✅ Filter sensitive actions
* ✅ Sanitize inputs and outputs
* ✅ Monitor performance and errors
* ✅ Provide clear error messages
* ✅ Use descriptive names and descriptions
* ✅ Keep tools focused and well-documented
* ✅ Set up comprehensive logging and alerting

***

## Next Steps

* Review [Advanced Configuration](/docs/mcp-server/advanced) for fine-tuning
* Learn about [Event Handlers](/docs/mcp-server/events) for monitoring
* Explore [OAuth](/docs/mcp-server/oauth) for security


---

# Builder Pattern API

> Use the fluent builder pattern API for full type inference and step-by-step configuration of your MCP server.
URL: https://igniterjs.com/docs/mcp-server/builder-pattern

## Overview

The Builder Pattern API (`IgniterMcpServer`) provides a fluent, chainable interface for configuring your MCP server. It offers full TypeScript type inference, better IDE autocomplete, and explicit separation of concerns.

<Callout type="success" title="Recommended">
  The builder pattern is recommended for TypeScript projects where you want maximum type safety and a clear, progressive configuration flow.
</Callout>

***

## Basic Usage

### Creating a Server

Start by calling `IgniterMcpServer.create()` and chain configuration methods:

```typescript
import { IgniterMcpServer } from '@igniter-js/adapter-mcp-server';
import { AppRouter } from '@/igniter.router';

const { handler, auth } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withServerInfo({
    name: 'My MCP Server',
    version: '1.0.0',
  })
  .build();

export const GET = handler;
export const POST = handler;
```

***

## Configuration Methods

### router()

Sets the Igniter.js router to expose as MCP tools. **This method is required.**

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter) // Required: Your Igniter router
  .build();
```

**Type Safety**: After calling `.router()`, all subsequent methods benefit from type inference based on your router's context type.

***

### withServerInfo()

Sets metadata about your MCP server:

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withServerInfo({
    name: 'Acme Corporation API',
    version: '1.2.0',
  })
  .build();
```

**Parameters:**

* `name` (string): Server name displayed to MCP clients
* `version` (string): Server version (semantic versioning recommended)

***

### withInstructions()

Provides instructions to AI agents about how to use your server:

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withInstructions(
    "This server provides tools to manage users and products. " +
    "Use users.list to get all users, users.create to add new users, " +
    "and products.search to find products by keyword."
  )
  .build();
```

**Best Practices:**

* Describe what your API does
* List key tools and their purposes
* Mention any important usage patterns or constraints

***

### withCapabilities()

Configure server capabilities to advertise to MCP clients:

```typescript
import { ServerCapabilities } from '@modelcontextprotocol/sdk/types';

const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withCapabilities({
    tools: {},
    prompts: {},
    resources: {},
  })
  .build();
```

***

### addTool()

Add custom tools beyond your router actions. Each tool gets full type inference:

```typescript
import { z } from 'zod';

const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .addTool({
    name: 'calculateTax',
    description: 'Calculate tax for a given amount',
    args: {
      amount: z.number(),
      taxRate: z.number(),
    },
    handler: async (args, context) => {
      // context is automatically typed from your router!
      const tax = args.amount * args.taxRate;
      return {
        content: [{
          type: 'text',
          text: `Tax: $${tax.toFixed(2)}`
        }]
      };
    },
  })
  .build();
```

**Type Inference:**

* `args` is automatically typed based on your Zod schema
* `context` is automatically typed from your router's context type
* Return type is validated to match MCP's `CallToolResult`

**Multiple Tools:**

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .addTool({ /* tool 1 */ })
  .addTool({ /* tool 2 */ })
  .addTool({ /* tool 3 */ })
  .build();
```

***

### addPrompt()

Register prompts that AI agents can use to guide interactions:

```typescript
import { z } from 'zod';

const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .addPrompt({
    name: 'debugUser',
    description: 'Debug user account issues',
    args: {
      userId: z.string(),
    },
    handler: async (args, context) => {
      // context is automatically typed!
      return {
        messages: [{
          role: 'user',
          content: {
            type: 'text',
            text: `Please debug the account for user ${args.userId}. ` +
                  `Check their permissions, recent activity, and any error logs.`
          }
        }]
      };
    },
  })
  .build();
```

**Use Cases:**

* Create debugging prompts that combine multiple steps
* Guide AI agents through complex workflows
* Provide context-aware instructions

***

### addResource()

Expose resources that AI agents can read:

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .addResource({
    uri: 'config://app/settings',
    name: 'Application Settings',
    description: 'Current application configuration',
    mimeType: 'application/json',
    handler: async (context) => {
      // context is automatically typed!
      const settings = await getAppSettings();
      return {
        contents: [{
          uri: 'config://app/settings',
          mimeType: 'application/json',
          text: JSON.stringify(settings, null, 2)
        }]
      };
    }
  })
  .build();
```

**Resource URI Patterns:**

* `config://` - Configuration resources
* `file://` - File-based resources
* `db://` - Database resources
* Custom schemes are also supported

***

### withOAuth()

Secure your MCP server with OAuth authentication:

```typescript
const { handler, auth } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withOAuth({
    issuer: 'https://auth.example.com',
    resourceMetadataPath: '/.well-known/oauth-protected-resource',
    scopes: ['mcp:read', 'mcp:write'],
    verifyToken: async ({ request, bearerToken, context }) => {
      // context is automatically typed!
      const result = await verifyJWT(bearerToken);
      return {
        valid: result.valid,
        user: result.user
      };
    }
  })
  .build();

// Export the handler and OAuth endpoints
export const GET = handler;
export const POST = handler;
export const OPTIONS = auth.cors;

// In your OAuth metadata endpoint route (e.g., /.well-known/oauth-protected-resource)
// export { auth.resource as GET };
```

**OAuth Features:**

* Automatic Bearer token validation
* Custom token verification logic
* OAuth metadata endpoint
* CORS support for OAuth flows

***

### withEvents()

Monitor and log MCP operations:

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withEvents({
    onRequest: async (request, context) => {
      console.log('MCP request received:', request.url);
    },
    onResponse: async (response, context) => {
      console.log('MCP response sent');
    },
    onToolCall: async (toolName, args, context) => {
      console.log(`Tool called: ${toolName}`, args);
    },
    onToolSuccess: async (toolName, result, duration, context) => {
      console.log(`Tool ${toolName} completed in ${duration}ms`);
    },
    onToolError: async (toolName, error, context) => {
      console.error(`Tool ${toolName} failed:`, error);
    },
    onError: async (error, context) => {
      console.error('MCP adapter error:', error);
    }
  })
  .build();
```

**Available Events:**

* `onRequest` - Called when any MCP request is received
* `onResponse` - Called when a response is sent
* `onToolCall` - Called when a tool is invoked
* `onToolSuccess` - Called when a tool completes successfully
* `onToolError` - Called when a tool fails
* `onError` - Called on general adapter errors

***

### withToolTransform()

Customize how router actions are transformed into tools:

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withToolTransform((controller, action, actionConfig) => {
    // Customize tool name
    const name = `${controller}_${action}`;
    
    // Use summary if available, fallback to description
    const description = actionConfig.summary || 
                       actionConfig.description || 
                       `Execute ${controller} ${action}`;
    
    // Include tags from action config
    const tags = actionConfig.tags || [];
    
    return {
      name,
      description,
      schema: actionConfig.body || actionConfig.query || {},
      tags: [...tags, controller, actionConfig.method?.toLowerCase()].filter(Boolean)
    };
  })
  .build();
```

**Use Cases:**

* Custom naming strategies
* Enhanced descriptions
* Additional metadata (tags, categories)
* Schema transformations

***

### withLogger()

Configure custom logging:

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withLogger({
    log: (message) => console.log(`[MCP] ${message}`),
    error: (message) => console.error(`[MCP ERROR] ${message}`),
    warn: (message) => console.warn(`[MCP WARN] ${message}`),
    debug: (message) => console.debug(`[MCP DEBUG] ${message}`),
  })
  .build();
```

***

### withResponse()

Customize response transformation and error handling:

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withResponse({
    transform: async (igniterResponse, toolName, context) => {
      // Customize how Igniter responses are formatted for MCP
      return {
        content: [{
          type: 'text',
          text: JSON.stringify(igniterResponse, null, 2)
        }]
      };
    },
    onError: async (error, toolName, context) => {
      // Custom error handling
      return {
        content: [{
          type: 'text',
          text: `Error in ${toolName}: ${error.message}`
        }]
      };
    }
  })
  .build();
```

***

## Complete Example

Here's a complete example combining multiple features:

```typescript
import { IgniterMcpServer } from '@igniter-js/adapter-mcp-server';
import { AppRouter } from '@/igniter.router';
import { z } from 'zod';

const { handler, auth } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withServerInfo({
    name: 'Acme Corporation API',
    version: '1.0.0',
  })
  .withInstructions(
    "This server provides tools to manage users, products, and orders. " +
    "Use the appropriate tools to interact with each resource."
  )
  .addTool({
    name: 'calculateTax',
    description: 'Calculate tax for an amount',
    args: {
      amount: z.number(),
      taxRate: z.number(),
    },
    handler: async (args, context) => {
      const tax = args.amount * args.taxRate;
      return {
        content: [{
          type: 'text',
          text: `Tax: $${tax.toFixed(2)}`
        }]
      };
    },
  })
  .addPrompt({
    name: 'debugUser',
    description: 'Debug user account',
    args: { userId: z.string() },
    handler: async (args, context) => {
      return {
        messages: [{
          role: 'user',
          content: {
            type: 'text',
            text: `Debug user ${args.userId}`
          }
        }]
      };
    },
  })
  .addResource({
    uri: 'config://app/settings',
    name: 'App Settings',
    description: 'Application configuration',
    mimeType: 'application/json',
    handler: async (context) => {
      const settings = await getAppSettings();
      return {
        contents: [{
          uri: 'config://app/settings',
          mimeType: 'application/json',
          text: JSON.stringify(settings, null, 2)
        }]
      };
    }
  })
  .withOAuth({
    issuer: 'https://auth.example.com',
    verifyToken: async ({ bearerToken, context }) => {
      const result = await verifyJWT(bearerToken);
      return { valid: result.valid, user: result.user };
    }
  })
  .withEvents({
    onToolCall: async (toolName, args, context) => {
      console.log(`Tool called: ${toolName}`);
    },
    onToolError: async (toolName, error, context) => {
      console.error(`Tool error: ${toolName}`, error);
    }
  })
  .build();

export const GET = handler;
export const POST = handler;
export const OPTIONS = auth.cors;
```

***

## Type Safety Benefits

The builder pattern provides excellent type safety:

**1. Router Context Inference:**

```typescript
// Context type is automatically inferred from AppRouter
.handler(async (args, context) => {
  // ✅ context.db is typed
  // ✅ context.services is typed
  // ✅ All your context properties are available
})
```

**2. Tool Arguments:**

```typescript
.addTool({
  args: {
    amount: z.number(),
    email: z.string().email(),
  },
  handler: async (args, context) => {
    // ✅ args.amount is number
    // ✅ args.email is string
    // ✅ TypeScript enforces correct usage
  }
})
```

**3. Chain Type Safety:**

```typescript
// Each method returns a properly typed builder
const builder = IgniterMcpServer.create()
  .router(AppRouter) // Now knows about AppRouter's context
  .addTool({ /* Full type inference */ })
  .addPrompt({ /* Full type inference */ })
  .build(); // Returns properly typed handler
```

***

## Next Steps

* Learn about the [Function API](/docs/mcp-server/function-api) for simpler setups
* Explore [Custom Tools](/docs/mcp-server/custom-tools) in detail
* Check out [Advanced Configurations](/docs/mcp-server/advanced)


---

# Custom Tools

> Add custom tools beyond your router actions to extend your MCP server's capabilities.
URL: https://igniterjs.com/docs/mcp-server/custom-tools

## Overview

While the adapter automatically exposes all your Igniter.js router actions as MCP tools, you can also add custom tools that don't correspond to any router action. Custom tools are useful for:

* Utility functions (calculations, formatting, etc.)
* External API integrations
* Business logic operations
* Data transformations

***

## Adding Custom Tools

### Builder Pattern

```typescript
import { IgniterMcpServer } from '@igniter-js/adapter-mcp-server';
import { z } from 'zod';

const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .addTool({
    name: 'calculateTax',
    description: 'Calculate tax for a given amount',
    args: {
      amount: z.number().describe('The amount to calculate tax for'),
      taxRate: z.number().min(0).max(1).describe('Tax rate as decimal (e.g., 0.08 for 8%)'),
    },
    handler: async (args, context) => {
      // context is automatically typed from your router!
      const tax = args.amount * args.taxRate;
      const total = args.amount + tax;
      
      return {
        content: [{
          type: 'text',
          text: `Amount: $${args.amount.toFixed(2)}\n` +
                `Tax (${(args.taxRate * 100).toFixed(1)}%): $${tax.toFixed(2)}\n` +
                `Total: $${total.toFixed(2)}`
        }]
      };
    },
  })
  .build();
```

### Function API

```typescript
import { createMcpAdapter } from '@igniter-js/adapter-mcp-server';
import { z } from 'zod';

const { server } = createMcpAdapter({
  router: AppRouter,
  tools: {
    custom: [{
      name: 'calculateTax',
      description: 'Calculate tax for a given amount',
      args: {
        amount: z.number(),
        taxRate: z.number().min(0).max(1),
      },
      handler: async (args, context) => {
        const tax = args.amount * args.taxRate;
        return {
          content: [{
            type: 'text',
            text: `Tax: $${tax.toFixed(2)}`
          }]
        };
      }
    }]
  }
});
```

***

## Tool Definition

### Required Fields

**`name`** (string): Tool name (must be MCP-compliant, will be sanitized automatically)

**`description`** (string): Tool description shown to AI agents

**`args`** (ZodRawShape): Zod schema defining tool arguments

**`handler`** (function): Async function that executes the tool

***

## Tool Arguments Schema

Define arguments using Zod schemas. These are automatically converted to JSON Schema for MCP:

```typescript
.addTool({
  name: 'processOrder',
  description: 'Process an order with validation',
  args: {
    orderId: z.string().uuid().describe('Order UUID'),
    items: z.array(z.object({
      productId: z.string(),
      quantity: z.number().int().positive(),
      price: z.number().positive(),
    })).min(1).describe('Order items'),
    shippingAddress: z.object({
      street: z.string(),
      city: z.string(),
      state: z.string().length(2),
      zipCode: z.string().regex(/^\d{5}$/),
    }).describe('Shipping address'),
    priority: z.enum(['standard', 'express', 'overnight']).default('standard'),
  },
  handler: async (args, context) => {
    // args is fully typed based on the schema above
    // args.orderId is string
    // args.items is array of { productId, quantity, price }
    // args.shippingAddress is { street, city, state, zipCode }
    // args.priority is 'standard' | 'express' | 'overnight'
    
    // Your tool logic here
    return {
      content: [{
        type: 'text',
        text: `Order ${args.orderId} processed successfully`
      }]
    };
  },
})
```

***

## Tool Handler

The handler function receives two arguments:

**`args`**: Tool arguments, typed based on your Zod schema

**`context`**: MCP context with router context, tools list, request info, etc.

```typescript
handler: async (args, context) => {
  // Access router context
  const db = context.context.db;
  const services = context.context.services;
  
  // Access request information
  const userAgent = context.client;
  const timestamp = context.timestamp;
  
  // Access available tools
  const availableTools = context.tools;
  
  // Your tool logic
  return {
    content: [{
      type: 'text',
      text: 'Tool result'
    }]
  };
}
```

***

## Return Format

Tools must return an MCP-compliant `CallToolResult`:

```typescript
// Simple text response
return {
  content: [{
    type: 'text',
    text: 'Result here'
  }]
};

// Multiple content items
return {
  content: [
    {
      type: 'text',
      text: 'Primary result'
    },
    {
      type: 'text',
      text: 'Additional information'
    }
  ]
};

// With data (for structured responses)
return {
  content: [{
    type: 'text',
    text: JSON.stringify({ result: 'data' }, null, 2)
  }]
};
```

***

## Practical Examples

### Example 1: Currency Converter

```typescript
.addTool({
  name: 'convertCurrency',
  description: 'Convert amount between currencies',
  args: {
    amount: z.number().positive(),
    from: z.string().length(3).describe('Source currency code (e.g., USD)'),
    to: z.string().length(3).describe('Target currency code (e.g., EUR)'),
  },
  handler: async (args, context) => {
    // In a real app, you'd call an exchange rate API
    const exchangeRates = await context.context.services.exchangeRates.getRate(args.from, args.to);
    const converted = args.amount * exchangeRates.rate;
    
    return {
      content: [{
        type: 'text',
        text: `${args.amount} ${args.from} = ${converted.toFixed(2)} ${args.to} ` +
              `(rate: ${exchangeRates.rate})`
      }]
    };
  },
})
```

### Example 2: Data Formatter

```typescript
.addTool({
  name: 'formatDate',
  description: 'Format a date in various formats',
  args: {
    date: z.string().or(z.coerce.date()),
    format: z.enum(['iso', 'us', 'european', 'relative']).default('iso'),
  },
  handler: async (args, context) => {
    const date = new Date(args.date);
    let formatted: string;
    
    switch (args.format) {
      case 'iso':
        formatted = date.toISOString();
        break;
      case 'us':
        formatted = date.toLocaleDateString('en-US');
        break;
      case 'european':
        formatted = date.toLocaleDateString('en-GB');
        break;
      case 'relative':
        const now = new Date();
        const diff = now.getTime() - date.getTime();
        const days = Math.floor(diff / (1000 * 60 * 60 * 24));
        formatted = days === 0 ? 'Today' : `${days} days ago`;
        break;
    }
    
    return {
      content: [{
        type: 'text',
        text: formatted
      }]
    };
  },
})
```

### Example 3: External API Integration

```typescript
.addTool({
  name: 'sendSlackMessage',
  description: 'Send a message to a Slack channel',
  args: {
    channel: z.string().describe('Slack channel name or ID'),
    message: z.string().min(1),
    threadTs: z.string().optional().describe('Thread timestamp for replies'),
  },
  handler: async (args, context) => {
    const slackService = context.context.services.slack;
    
    const result = await slackService.postMessage({
      channel: args.channel,
      text: args.message,
      thread_ts: args.threadTs,
    });
    
    return {
      content: [{
        type: 'text',
        text: `Message sent to ${args.channel} at ${result.ts}`
      }]
    };
  },
})
```

***

## Multiple Custom Tools

You can add multiple custom tools:

**Builder Pattern:**

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .addTool({ /* tool 1 */ })
  .addTool({ /* tool 2 */ })
  .addTool({ /* tool 3 */ })
  .build();
```

**Function API:**

```typescript
const { server } = createMcpAdapter({
  router: AppRouter,
  tools: {
    custom: [
      { /* tool 1 */ },
      { /* tool 2 */ },
      { /* tool 3 */ },
    ]
  }
});
```

***

## Error Handling

Handle errors gracefully in your tool handlers:

```typescript
.addTool({
  name: 'riskyOperation',
  description: 'Perform a risky operation',
  args: {
    input: z.string(),
  },
  handler: async (args, context) => {
    try {
      const result = await performRiskyOperation(args.input);
      return {
        content: [{
          type: 'text',
          text: `Success: ${result}`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
        }],
        isError: true
      };
    }
  },
})
```

***

## Best Practices

### 1. Descriptive Names and Descriptions

```typescript
// ✅ Good
{
  name: 'calculateTax',
  description: 'Calculate sales tax for a given amount based on location and tax rate',
}

// ❌ Bad
{
  name: 'tax',
  description: 'Calculate tax',
}
```

### 2. Use Zod Descriptions

Add `.describe()` to your schema fields to help AI agents understand parameters:

```typescript
args: {
  amount: z.number().describe('The monetary amount in USD'),
  taxRate: z.number().min(0).max(1).describe('Tax rate as decimal (0.08 = 8%)'),
}
```

### 3. Validate Inputs

Use Zod's validation features:

```typescript
args: {
  email: z.string().email(),
  age: z.number().int().min(0).max(150),
  status: z.enum(['active', 'inactive', 'pending']),
}
```

### 4. Provide Clear Error Messages

```typescript
handler: async (args, context) => {
  try {
    // Operation
  } catch (error) {
    return {
      content: [{
        type: 'text',
        text: `Failed to process: ${error.message}. Please check your inputs and try again.`
      }],
      isError: true
    };
  }
}
```

***

## Next Steps

* Learn about [Prompts & Resources](/docs/mcp-server/prompts-resources)
* Explore [Event Handlers](/docs/mcp-server/events) for monitoring
* Check out [Best Practices](/docs/mcp-server/best-practices)


---

# Event Handlers

> Monitor and log MCP operations using comprehensive event hooks for observability and debugging.
URL: https://igniterjs.com/docs/mcp-server/events

## Overview

The MCP Server adapter provides comprehensive event hooks that allow you to monitor, log, and respond to all MCP operations. This is essential for debugging, analytics, and maintaining observability of your MCP server.

***

## Available Events

The adapter supports the following events:

* `onRequest` - Called when any MCP request is received
* `onResponse` - Called when a response is sent
* `onToolCall` - Called when a tool is invoked
* `onToolSuccess` - Called when a tool completes successfully
* `onToolError` - Called when a tool fails
* `onError` - Called on general adapter errors

***

## Setting Up Event Handlers

### Builder Pattern

```typescript
import { IgniterMcpServer } from '@igniter-js/adapter-mcp-server';

const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withEvents({
    onRequest: async (request, context) => {
      console.log('MCP request received:', request.url);
    },
    onResponse: async (response, context) => {
      console.log('MCP response sent');
    },
    onToolCall: async (toolName, args, context) => {
      console.log(`Tool called: ${toolName}`, args);
    },
    onToolSuccess: async (toolName, result, duration, context) => {
      console.log(`Tool ${toolName} completed in ${duration}ms`);
    },
    onToolError: async (toolName, error, context) => {
      console.error(`Tool ${toolName} failed:`, error);
    },
    onError: async (error, context) => {
      console.error('MCP adapter error:', error);
    }
  })
  .build();
```

### Function API

```typescript
import { createMcpAdapter } from '@igniter-js/adapter-mcp-server';

const { server } = createMcpAdapter({
  router: AppRouter,
  events: {
    onRequest: async (request, context) => {
      console.log('MCP request received:', request.url);
    },
    onResponse: async (response, context) => {
      console.log('MCP response sent');
    },
    onToolCall: async (toolName, args, context) => {
      console.log(`Tool called: ${toolName}`, args);
    },
    onToolSuccess: async (toolName, result, duration, context) => {
      console.log(`Tool ${toolName} completed in ${duration}ms`);
    },
    onToolError: async (toolName, error, context) => {
      console.error(`Tool ${toolName} failed:`, error);
    },
    onError: async (error, context) => {
      console.error('MCP adapter error:', error);
    }
  }
});
```

***

## Event Details

### onRequest

Called when any MCP request is received:

```typescript
onRequest: async (request, context) => {
  // request: The incoming Request object
  // context: MCP context with router context, tools, etc.
  
  console.log('Request URL:', request.url);
  console.log('Request method:', request.method);
  console.log('Request headers:', Object.fromEntries(request.headers));
  
  // Log to analytics
  await analytics.track('mcp_request', {
    url: request.url,
    method: request.method,
    timestamp: context.timestamp,
  });
}
```

***

### onResponse

Called when a response is sent:

```typescript
onResponse: async (response, context) => {
  // response: The response that was sent
  // context: MCP context
  
  console.log('Response status:', response.status);
  console.log('Response headers:', Object.fromEntries(response.headers));
  
  // Log response metrics
  await metrics.record('mcp_response', {
    status: response.status,
    timestamp: context.timestamp,
  });
}
```

***

### onToolCall

Called when a tool is invoked (before execution):

```typescript
onToolCall: async (toolName, args, context) => {
  // toolName: Name of the tool being called
  // args: Arguments passed to the tool
  // context: MCP context
  
  console.log(`Tool called: ${toolName}`);
  console.log('Arguments:', args);
  
  // Log to audit trail
  await audit.log({
    type: 'tool_call',
    tool: toolName,
    args: sanitizeArgs(args), // Remove sensitive data
    timestamp: context.timestamp,
    client: context.client,
  });
  
  // Rate limiting check
  const rateLimitKey = `mcp:tool:${toolName}:${context.client}`;
  const isRateLimited = await checkRateLimit(rateLimitKey);
  
  if (isRateLimited) {
    throw new Error('Rate limit exceeded');
  }
}
```

***

### onToolSuccess

Called when a tool completes successfully:

```typescript
onToolSuccess: async (toolName, result, duration, context) => {
  // toolName: Name of the tool
  // result: Tool execution result
  // duration: Execution time in milliseconds
  // context: MCP context
  
  console.log(`Tool ${toolName} completed in ${duration}ms`);
  
  // Log performance metrics
  await metrics.record('tool_execution', {
    tool: toolName,
    duration,
    success: true,
    timestamp: context.timestamp,
  });
  
  // Alert on slow executions
  if (duration > 5000) {
    await alerts.send({
      type: 'slow_tool_execution',
      tool: toolName,
      duration,
    });
  }
}
```

***

### onToolError

Called when a tool fails:

```typescript
onToolError: async (toolName, error, context) => {
  // toolName: Name of the tool that failed
  // error: The error that occurred
  // context: MCP context
  
  console.error(`Tool ${toolName} failed:`, error);
  
  // Log error to monitoring service
  await monitoring.logError({
    tool: toolName,
    error: error.message,
    stack: error.stack,
    timestamp: context.timestamp,
  });
  
  // Send alert for critical failures
  if (isCriticalTool(toolName)) {
    await alerts.send({
      type: 'critical_tool_failure',
      tool: toolName,
      error: error.message,
    });
  }
  
  // Update error tracking
  await errorTracking.increment({
    tool: toolName,
    errorType: error.constructor.name,
  });
}
```

***

### onError

Called on general adapter errors (not tool-specific):

```typescript
onError: async (error, context) => {
  // error: The error that occurred
  // context: MCP context
  
  console.error('MCP adapter error:', error);
  
  // Log to error tracking service
  await errorTracking.log({
    error: error.message,
    stack: error.stack,
    context: {
      url: context.request?.url,
      method: context.request?.method,
      timestamp: context.timestamp,
    },
  });
  
  // Send critical alert
  await alerts.send({
    type: 'mcp_adapter_error',
    error: error.message,
    severity: 'critical',
  });
}
```

***

## Practical Examples

### Example 1: Request Logging

```typescript
.withEvents({
  onRequest: async (request, context) => {
    const logEntry = {
      timestamp: new Date().toISOString(),
      method: request.method,
      url: request.url,
      userAgent: request.headers.get('user-agent'),
      ip: request.headers.get('x-forwarded-for') || 'unknown',
    };
    
    // Log to file or database
    await logger.info('MCP Request', logEntry);
  }
})
```

### Example 2: Performance Monitoring

```typescript
.withEvents({
  onToolSuccess: async (toolName, result, duration, context) => {
    // Track execution times
    await metrics.histogram('tool_execution_duration', duration, {
      tool: toolName,
    });
    
    // Track success rate
    await metrics.increment('tool_executions_total', {
      tool: toolName,
      status: 'success',
    });
    
    // Alert on slow tools
    if (duration > 10000) {
      await alerts.warn(`Tool ${toolName} took ${duration}ms to execute`);
    }
  },
  onToolError: async (toolName, error, context) => {
    // Track error rate
    await metrics.increment('tool_executions_total', {
      tool: toolName,
      status: 'error',
    });
  }
})
```

### Example 3: Audit Trail

```typescript
.withEvents({
  onToolCall: async (toolName, args, context) => {
    // Create audit log entry
    await audit.create({
      action: 'tool_call',
      tool: toolName,
      user: context.context.user?.id || 'anonymous',
      args: sanitizeForAudit(args),
      timestamp: new Date(),
      ip: context.request.headers.get('x-forwarded-for'),
    });
  }
})
```

### Example 4: Rate Limiting

```typescript
.withEvents({
  onToolCall: async (toolName, args, context) => {
    const clientId = context.client || 'unknown';
    const rateLimitKey = `mcp:${clientId}:${toolName}`;
    
    const remaining = await rateLimiter.check(rateLimitKey, {
      limit: 100, // 100 calls per window
      window: 60000, // 1 minute window
    });
    
    if (remaining < 0) {
      throw new Error('Rate limit exceeded. Please try again later.');
    }
    
    // Set rate limit headers in response
    context.request.headers.set('X-RateLimit-Remaining', remaining.toString());
  }
})
```

### Example 5: Error Tracking and Alerting

```typescript
.withEvents({
  onToolError: async (toolName, error, context) => {
    // Track error frequency
    const errorKey = `error:${toolName}:${error.constructor.name}`;
    const count = await errorCounter.increment(errorKey);
    
    // Alert if error threshold exceeded
    if (count > 10) {
      await alerts.send({
        type: 'high_error_rate',
        tool: toolName,
        error: error.message,
        count,
      });
    }
    
    // Log to error tracking service
    await sentry.captureException(error, {
      tags: {
        tool: toolName,
        component: 'mcp_adapter',
      },
      extra: {
        args: context.request.body,
        name: toolName,
      },
    });
  }
})
```

***

## Context in Event Handlers

All event handlers receive a `context` object with:

```typescript
interface McpContext {
  context: TContext; // Your router's context
  tools: McpToolInfo[]; // Available tools
  request: Request; // Current request
  timestamp: number; // Request timestamp
  client?: string; // Client identifier
  server?: McpServer; // MCP server instance
}
```

***

## Best Practices

### 1. Keep Handlers Async

All event handlers are async and should use `await` for any async operations:

```typescript
// ✅ Good
onToolCall: async (toolName, args, context) => {
  await logger.log(toolName, args);
}

// ❌ Bad - Synchronous operations can block
onToolCall: (toolName, args, context) => {
  fs.writeFileSync('log.txt', toolName); // Blocks!
}
```

### 2. Don't Throw in Handlers

Event handlers shouldn't throw errors. Handle errors gracefully:

```typescript
// ✅ Good
onToolCall: async (toolName, args, context) => {
  try {
    await logger.log(toolName, args);
  } catch (error) {
    console.error('Failed to log:', error);
    // Don't throw - just log the error
  }
}

// ❌ Bad - Throwing can break the flow
onToolCall: async (toolName, args, context) => {
  await logger.log(toolName, args); // If this throws, tool won't execute!
}
```

### 3. Sanitize Sensitive Data

Remove sensitive information before logging:

```typescript
onToolCall: async (toolName, args, context) => {
  const sanitized = sanitizeArgs(args, {
    removeFields: ['password', 'token', 'secret'],
    maskFields: ['email', 'creditCard'],
  });
  
  await logger.log(toolName, sanitized);
}
```

### 4. Use Structured Logging

Use structured logging for better queryability:

```typescript
onToolCall: async (toolName, args, context) => {
  await logger.info({
    event: 'tool_call',
    tool: toolName,
    args: sanitizeArgs(args),
    timestamp: context.timestamp,
    client: context.client,
  });
}
```

***

## Next Steps

* Explore [Advanced Configurations](/docs/mcp-server/advanced)
* Check out [Best Practices](/docs/mcp-server/best-practices)
* Learn about [OAuth](/docs/mcp-server/oauth) for securing your server


---

# Function API

> Use the simple function-based API for straightforward MCP server configurations.
URL: https://igniterjs.com/docs/mcp-server/function-api

## Overview

The Function API (`createMcpAdapter`) provides a simpler, single-object configuration approach. It's ideal for basic setups and JavaScript projects where you prefer configuration over a fluent API.

<Callout type="info">
  For TypeScript projects seeking maximum type safety, consider using the [Builder Pattern API](/docs/mcp-server/builder-pattern) instead.
</Callout>

***

## Basic Usage

### Simple Configuration

The function API accepts a single configuration object:

```typescript
import { createMcpAdapter } from '@igniter-js/adapter-mcp-server';
import { AppRouter } from '@/igniter.router';

const { server, auth } = createMcpAdapter({
  router: AppRouter,
  serverInfo: {
    name: 'My MCP Server',
    version: '1.0.0',
  },
  instructions: "Use the available tools to manage users and products.",
});

export const GET = server;
export const POST = server;
```

***

## Configuration Options

### router (Required)

The Igniter.js router to expose as MCP tools:

```typescript
const { server } = createMcpAdapter({
  router: AppRouter, // Required
});
```

***

### serverInfo

Server metadata:

```typescript
const { server } = createMcpAdapter({
  router: AppRouter,
  serverInfo: {
    name: 'Acme Corporation API',
    version: '1.2.0',
  },
});
```

***

### instructions

Instructions for AI agents:

```typescript
const { server } = createMcpAdapter({
  router: AppRouter,
  instructions: "This server provides tools to manage users and products.",
});
```

***

### tools

Customize tool generation and add custom tools:

```typescript
import { z } from 'zod';

const { server } = createMcpAdapter({
  router: AppRouter,
  tools: {
    // Automatically map all router actions (default: true)
    autoMap: true,
    
    // Custom naming strategy
    naming: (controller, action) => `${controller}_${action}`,
    
    // Filter which actions to expose
    filter: (controller, action, actionConfig) => {
      // Only expose actions with a specific tag
      return actionConfig.tags?.includes('mcp-enabled');
    },
    
    // Transform action configurations
    transform: (controller, action, actionConfig) => ({
      name: `${controller}.${action}`,
      description: actionConfig.summary || actionConfig.description,
      schema: actionConfig.body || actionConfig.query || {},
      tags: actionConfig.tags
    }),
    
    // Custom tools
    custom: [{
      name: 'calculateTax',
      description: 'Calculate tax for a given amount',
      args: {
        amount: z.number(),
        taxRate: z.number(),
      },
      handler: async (args, context) => {
        const tax = args.amount * args.taxRate;
        return {
          content: [{
            type: 'text',
            text: `Tax: $${tax.toFixed(2)}`
          }]
        };
      }
    }]
  }
});
```

***

### prompts

Register custom prompts:

```typescript
import { z } from 'zod';

const { server } = createMcpAdapter({
  router: AppRouter,
  prompts: {
    custom: [{
      name: 'debugUser',
      description: 'Debug user account issues',
      args: {
        userId: z.string(),
      },
      handler: async (args, context) => {
        return {
          messages: [{
            role: 'user',
            content: {
              type: 'text',
              text: `Please debug the account for user ${args.userId}.`
            }
          }]
        };
      }
    }]
  }
});
```

***

### resources

Expose custom resources:

```typescript
const { server } = createMcpAdapter({
  router: AppRouter,
  resources: {
    custom: [{
      uri: 'config://app/settings',
      name: 'Application Settings',
      description: 'Current application configuration',
      mimeType: 'application/json',
      handler: async (context) => {
        const settings = await getAppSettings();
        return {
          contents: [{
            uri: 'config://app/settings',
            mimeType: 'application/json',
            text: JSON.stringify(settings, null, 2)
          }]
        };
      }
    }]
  }
});
```

***

### oauth

Configure OAuth authentication:

```typescript
const { server, auth } = createMcpAdapter({
  router: AppRouter,
  oauth: {
    issuer: 'https://auth.example.com',
    resourceMetadataPath: '/.well-known/oauth-protected-resource',
    scopes: ['mcp:read', 'mcp:write'],
    verifyToken: async ({ request, bearerToken, context }) => {
      const result = await verifyJWT(bearerToken);
      return {
        valid: result.valid,
        user: result.user
      };
    }
  }
});

// Export OAuth endpoints
export const GET = server;
export const POST = server;
export const OPTIONS = auth.cors;
```

***

### events

Monitor MCP operations:

```typescript
const { server } = createMcpAdapter({
  router: AppRouter,
  events: {
    onRequest: async (request, context) => {
      console.log('MCP request received:', request.url);
    },
    onResponse: async (response, context) => {
      console.log('MCP response sent');
    },
    onToolCall: async (toolName, args, context) => {
      console.log(`Tool called: ${toolName}`, args);
    },
    onToolSuccess: async (toolName, result, duration, context) => {
      console.log(`Tool ${toolName} completed in ${duration}ms`);
    },
    onToolError: async (toolName, error, context) => {
      console.error(`Tool ${toolName} failed:`, error);
    },
    onError: async (error, context) => {
      console.error('MCP adapter error:', error);
    }
  }
});
```

***

### response

Customize response transformation:

```typescript
const { server } = createMcpAdapter({
  router: AppRouter,
  response: {
    transform: async (igniterResponse, toolName, context) => {
      // Customize response format
      return {
        content: [{
          type: 'text',
          text: JSON.stringify(igniterResponse, null, 2)
        }]
      };
    },
    onError: async (error, toolName, context) => {
      // Custom error handling
      return {
        content: [{
          type: 'text',
          text: `Error in ${toolName}: ${error.message}`
        }]
      };
    }
  }
});
```

***

### adapter

Adapter-specific options:

```typescript
const { server } = createMcpAdapter({
  router: AppRouter,
  adapter: {
    basePath: '/api/mcp',
    maxDuration: 60,
    verboseLogs: true,
    redis: {
      url: process.env.REDIS_URL,
    }
  }
});
```

***

## Complete Example

Here's a complete example with multiple features:

```typescript
import { createMcpAdapter } from '@igniter-js/adapter-mcp-server';
import { AppRouter } from '@/igniter.router';
import { z } from 'zod';

const { server, auth } = createMcpAdapter({
  router: AppRouter,
  serverInfo: {
    name: 'Acme Corporation API',
    version: '1.0.0',
  },
  instructions: "This server provides tools to manage users and products.",
  tools: {
    custom: [{
      name: 'calculateTax',
      description: 'Calculate tax',
      args: {
        amount: z.number(),
        taxRate: z.number(),
      },
      handler: async (args, context) => {
        const tax = args.amount * args.taxRate;
        return {
          content: [{
            type: 'text',
            text: `Tax: $${tax.toFixed(2)}`
          }]
        };
      }
    }]
  },
  prompts: {
    custom: [{
      name: 'debugUser',
      description: 'Debug user account',
      args: { userId: z.string() },
      handler: async (args, context) => {
        return {
          messages: [{
            role: 'user',
            content: {
              type: 'text',
              text: `Debug user ${args.userId}`
            }
          }]
        };
      }
    }]
  },
  resources: {
    custom: [{
      uri: 'config://app/settings',
      name: 'App Settings',
      description: 'Application configuration',
      mimeType: 'application/json',
      handler: async (context) => {
        const settings = await getAppSettings();
        return {
          contents: [{
            uri: 'config://app/settings',
            mimeType: 'application/json',
            text: JSON.stringify(settings, null, 2)
          }]
        };
      }
    }]
  },
  oauth: {
    issuer: 'https://auth.example.com',
    verifyToken: async ({ bearerToken, context }) => {
      const result = await verifyJWT(bearerToken);
      return { valid: result.valid, user: result.user };
    }
  },
  events: {
    onToolCall: async (toolName, args, context) => {
      console.log(`Tool called: ${toolName}`);
    }
  }
});

export const GET = server;
export const POST = server;
export const OPTIONS = auth.cors;
```

***

## Comparison: Function API vs Builder Pattern

| Feature             | Function API              | Builder Pattern            |
| ------------------- | ------------------------- | -------------------------- |
| Type Inference      | Partial                   | Full                       |
| IDE Autocomplete    | Good                      | Excellent                  |
| Configuration Style | Single object             | Chainable methods          |
| Best For            | Simple setups, JavaScript | Complex setups, TypeScript |
| Verbosity           | Less verbose              | More explicit              |

***

## When to Use Function API

**Choose Function API when:**

* You prefer a single configuration object
* Working in JavaScript (not TypeScript)
* You have a simple setup
* You want less verbose code

**Choose Builder Pattern when:**

* You need full type inference
* Working in TypeScript
* You have complex configurations
* You want progressive configuration

***

## Next Steps

* Learn about the [Builder Pattern API](/docs/mcp-server/builder-pattern) for advanced type safety
* Explore [Custom Tools](/docs/mcp-server/custom-tools) in detail
* Check out [Advanced Configurations](/docs/mcp-server/advanced)


---

# Getting Started

> Learn how to set up and use the MCP Server adapter to expose your Igniter.js API as an MCP server.
URL: https://igniterjs.com/docs/mcp-server/getting-started

## Introduction

This guide will walk you through setting up the MCP Server adapter step-by-step. By the end, you'll have a working MCP server that exposes your Igniter.js API to AI agents.

***

## Prerequisites

Before you begin, ensure you have:

* An Igniter.js application with at least one controller and action
* A Next.js application (or compatible framework)
* Node.js 18+ installed

***

## Step 1: Create Your Igniter.js Router

First, ensure you have an Igniter.js router with some controllers and actions:

```typescript
// src/igniter.router.ts
import { igniter } from '@/igniter';
import { z } from 'zod';

export const usersController = igniter.controller({
  path: '/users',
  actions: {
    list: igniter.query({
      path: '/',
      handler: async ({ context, response }) => {
        const users = await context.db.users.findMany();
        return response.success({ users });
      },
    }),
    
    getById: igniter.query({
      path: '/:id',
      handler: async ({ request, response }) => {
        const user = await context.db.users.findUnique({
          where: { id: request.params.id },
        });
        return response.success({ user });
      },
    }),
    
    create: igniter.mutation({
      path: '/',
      method: 'POST',
      body: z.object({
        email: z.string().email(),
        name: z.string(),
      }),
      handler: async ({ request, response }) => {
        const user = await context.db.users.create({
          data: request.body,
        });
        return response.created({ user });
      },
    }),
  },
});

export const AppRouter = igniter.merge({
  users: usersController,
});
```

***

## Step 2: Create the MCP Route Handler

Create a new API route in your Next.js application:

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="app">
      <Folder name="api">
        <Folder name="mcp">
          <Folder name="[...transport]">
            <File name="route.ts" />
          </Folder>
        </Folder>
      </Folder>
    </Folder>
  </Folder>
</Files>

**Using Builder Pattern:**

```typescript
// src/app/api/mcp/[...transport]/route.ts
import { IgniterMcpServer } from '@igniter-js/adapter-mcp-server';
import { AppRouter } from '@/igniter.router';

const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withServerInfo({
    name: 'My API MCP Server',
    version: '1.0.0',
  })
  .withInstructions(
    "This server provides tools to manage users in the system. " +
    "Use the users.list tool to get all users, users.getById to get a specific user, " +
    "and users.create to create a new user."
  )
  .build();

export const GET = handler;
export const POST = handler;
```

**Using Function API:**

```typescript
// src/app/api/mcp/[...transport]/route.ts
import { createMcpAdapter } from '@igniter-js/adapter-mcp-server';
import { AppRouter } from '@/igniter.router';

const { server } = createMcpAdapter({
  router: AppRouter,
  serverInfo: {
    name: 'My API MCP Server',
    version: '1.0.0',
  },
  instructions: "This server provides tools to manage users in the system.",
});

export const GET = server;
export const POST = server;
```

***

## Step 3: Start Your Development Server

Start your Next.js development server:

```bash
npm run dev
```

Your MCP server will be available at:

```
http://localhost:3000/api/mcp/sse
```

***

## Step 4: Connect from an MCP Client

### Cursor IDE

1. Open Cursor settings
2. Navigate to **Features** → **Model Context Protocol**
3. Click **Add Server**
4. Configure:
   * **Name**: `My Igniter API`
   * **URL**: `http://localhost:3000/api/mcp/sse`
   * **Transport**: `SSE` (Server-Sent Events)

### Claude Desktop

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "igniter-api": {
      "url": "http://localhost:3000/api/mcp/sse",
      "transport": "sse"
    }
  }
}
```

***

## Step 5: Test Your MCP Server

After connecting, you can test your MCP server by asking the AI agent:

**Example Prompts:**

* "List all users in the system"
* "Get user with ID '123'"
* "Create a new user with email '[test@example.com](mailto:test@example.com)' and name 'Test User'"

The AI agent will automatically:

1. Discover available tools from your MCP server
2. Select the appropriate tool (`users.list`, `users.getById`, or `users.create`)
3. Execute the tool with the correct parameters
4. Return the result in a natural language response

***

## Understanding Tool Names

The adapter automatically generates tool names from your controller and action names:

* Controller: `users`, Action: `list` → Tool: `users_list`
* Controller: `users`, Action: `getById` → Tool: `users_getById`
* Controller: `users`, Action: `create` → Tool: `users_create`

<Callout type="info">
  Tool names are sanitized to be MCP-compliant. Special characters are replaced, and names are normalized. You can customize this behavior using the `naming` option in advanced configurations.
</Callout>

***

## Understanding Tool Schemas

The adapter automatically converts your Zod schemas to JSON Schema:

```typescript
// Your Igniter action
create: igniter.mutation({
  body: z.object({
    email: z.string().email(),
    name: z.string(),
  }),
  // ...
})

// Becomes MCP tool with schema:
{
  "type": "object",
  "properties": {
    "body": {
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "name": { "type": "string" }
      },
      "required": ["email", "name"]
    }
  }
}
```

The AI agent will automatically understand the required parameters and their types.

***

## Common Patterns

### Passing Arguments

When an AI agent calls a tool, arguments are passed based on your action's schema:

**Query Actions** - Arguments come from `query` or `params`:

```typescript
// Action definition
getById: igniter.query({
  path: '/:id',
  // ...
})

// AI calls: users_getById({ params: { id: "123" } })
```

**Mutation Actions** - Arguments come from `body`:

```typescript
// Action definition
create: igniter.mutation({
  body: z.object({ email: z.string().email() }),
  // ...
})

// AI calls: users_create({ body: { email: "test@example.com" } })
```

***

## Next Steps

* Learn about the [Builder Pattern](/docs/mcp-server/builder-pattern) for advanced configurations
* Explore [Custom Tools](/docs/mcp-server/custom-tools) to extend your server
* Check out [OAuth](/docs/mcp-server/oauth) for securing your MCP server
* See [Events](/docs/mcp-server/events) for monitoring and logging


---

# MCP Server

> Transform your Igniter.js API into an AI-native MCP server that exposes your endpoints as tools consumable by AI agents and applications.
URL: https://igniterjs.com/docs/mcp-server

## Overview

The MCP Server adapter transforms your entire Igniter.js API into a **Model Context Protocol (MCP)** server, making your endpoints accessible as tools for AI agents and MCP-compatible applications. This enables powerful AI-native workflows where agents can understand and execute your API actions directly.

<Callout type="info">
  MCP is an open protocol developed by Anthropic that enables AI assistants to interact with external tools and data sources. By exposing your Igniter.js API as an MCP server, you make it accessible to AI agents in IDEs like Cursor, Claude Desktop, and other MCP-compatible clients.
</Callout>

### Key Features

* **Automatic Tool Generation**: Every Igniter.js action becomes an MCP tool automatically
* **Type-Safe APIs**: Full TypeScript inference for tools, prompts, and resources
* **Two API Patterns**: Builder pattern (recommended) or function-based API
* **Custom Tools**: Add custom tools beyond your router actions
* **Prompts & Resources**: Expose prompts and resources for AI agents
* **OAuth Support**: Secure your MCP server with OAuth authentication
* **Event Hooks**: Monitor and log all MCP operations
* **AI-Friendly**: Designed to be easily understood and used by AI agents

***

## Installation

To use the MCP Server adapter, install it alongside `@igniter-js/core`:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/adapter-mcp-server @igniter-js/core
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/adapter-mcp-server @igniter-js/core
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/adapter-mcp-server @igniter-js/core
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/adapter-mcp-server @igniter-js/core
    ```
  </Tab>
</Tabs>

***

## Quick Start

### 1. Create the MCP Route Handler

Create a new API route in your Next.js application to handle MCP requests. For example: `src/app/api/mcp/[...transport]/route.ts`.

**Using Builder Pattern (Recommended):**

```typescript
// src/app/api/mcp/[...transport]/route.ts
import { IgniterMcpServer } from '@igniter-js/adapter-mcp-server';
import { AppRouter } from '@/igniter.router';

/**
 * Create the MCP server using the builder pattern.
 * This provides full type inference and a fluent API.
 */
const { handler, auth } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withServerInfo({
    name: 'Igniter.js MCP Server',
    version: '1.0.0',
  })
  .withInstructions("Use the available tools to manage users and products in the Acme Corporation API.")
  .build();

/**
 * Export the handler for Next.js to handle both GET and POST requests,
 * which are used by different MCP transport methods (like SSE and WebSockets).
 */
export const GET = handler;
export const POST = handler;
```

**Using Function API (Simple):**

```typescript
// src/app/api/mcp/[...transport]/route.ts
import { createMcpAdapter } from '@igniter-js/adapter-mcp-server';
import { AppRouter } from '@/igniter.router';

const { server, auth } = createMcpAdapter({
  router: AppRouter,
  serverInfo: {
    name: 'Igniter.js MCP Server',
    version: '1.0.0',
  },
  instructions: "Use the available tools to manage users and products.",
});

export const GET = server;
export const POST = server;
```

### 2. Connect from an MCP Client

With this handler in place, your Igniter.js API is now an MCP server. You can connect to it from any MCP-compatible client.

For example, in an AI-powered IDE like Cursor, you would configure your custom MCP server with the following URL:

```
http://localhost:3000/api/mcp/sse
```

The AI can now discover and call your API actions:

**AI Prompt:**

> "List the users in the system."

The MCP adapter will translate this into a call to `users.list` on your backend, execute it, and return the result to the AI.

***

## How It Works

### Automatic Tool Generation

The adapter automatically inspects your Igniter.js router and transforms each action into an MCP tool:

1. **Router Traversal**: The adapter iterates through all controllers and actions in your router
2. **Action-to-Tool Mapping**: Each `IgniterAction` (from `igniter.query` or `igniter.mutation`) becomes an MCP tool
3. **Schema Conversion**: Zod schemas from `body`, `query`, and `params` are converted to JSON Schema for MCP
4. **Tool Registration**: Tools are registered with the MCP server with sanitized names and descriptions

### Execution Flow

When an AI agent calls a tool:

1. **MCP Request**: The adapter receives an HTTP request with the tool name and arguments
2. **Tool Resolution**: The adapter finds the corresponding Igniter.js action
3. **Server-Side Invocation**: Uses `router.caller` for direct, type-safe execution (bypasses HTTP stack)
4. **Result Formatting**: Formats the result into MCP-compliant response format
5. **Response**: Returns the formatted result to the MCP client

***

## Next Steps

* Learn how to [Get Started](/docs/mcp-server/getting-started) with basic usage
* Explore the [Builder Pattern](/docs/mcp-server/builder-pattern) API for advanced configurations
* Check out [Custom Tools](/docs/mcp-server/custom-tools) to extend your MCP server
* See [OAuth](/docs/mcp-server/oauth) for securing your server


---

# OAuth Authentication

> Secure your MCP server with OAuth authentication and protect resources with Bearer tokens.
URL: https://igniterjs.com/docs/mcp-server/oauth

## Overview

The MCP Server adapter supports OAuth 2.0 authentication, allowing you to secure your server and control access to your tools and resources. This is especially important when exposing your API to external AI agents.

<Callout type="warn">
  If your MCP server contains sensitive data or operations, you should always enable OAuth authentication.
</Callout>

***

## Basic OAuth Setup

### Builder Pattern

```typescript
import { IgniterMcpServer } from '@igniter-js/adapter-mcp-server';

const { handler, auth } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withOAuth({
    issuer: 'https://auth.example.com',
    resourceMetadataPath: '/.well-known/oauth-protected-resource',
    scopes: ['mcp:read', 'mcp:write'],
    verifyToken: async ({ request, bearerToken, context }) => {
      // context is automatically typed from your router!
      const result = await verifyJWT(bearerToken);
      return {
        valid: result.valid,
        user: result.user
      };
    }
  })
  .build();

// Export the handler and OAuth endpoints
export const GET = handler;
export const POST = handler;
export const OPTIONS = auth.cors;
```

### Function API

```typescript
import { createMcpAdapter } from '@igniter-js/adapter-mcp-server';

const { server, auth } = createMcpAdapter({
  router: AppRouter,
  oauth: {
    issuer: 'https://auth.example.com',
    resourceMetadataPath: '/.well-known/oauth-protected-resource',
    scopes: ['mcp:read', 'mcp:write'],
    verifyToken: async ({ request, bearerToken, context }) => {
      const result = await verifyJWT(bearerToken);
      return {
        valid: result.valid,
        user: result.user
      };
    }
  }
});

export const GET = server;
export const POST = server;
export const OPTIONS = auth.cors;
```

***

## OAuth Configuration Options

### issuer (Required)

The OAuth authorization server URL:

```typescript
withOAuth({
  issuer: 'https://auth.example.com',
  // ...
})
```

### resourceMetadataPath (Optional)

Path to the OAuth protected resource metadata endpoint. Defaults to `/.well-known/oauth-protected-resource`:

```typescript
withOAuth({
  issuer: 'https://auth.example.com',
  resourceMetadataPath: '/.well-known/oauth-protected-resource',
  // ...
})
```

### scopes (Optional)

Required OAuth scopes:

```typescript
withOAuth({
  issuer: 'https://auth.example.com',
  scopes: ['mcp:read', 'mcp:write'],
  // ...
})
```

### verifyToken (Required)

Function to verify Bearer tokens. Receives the request, bearer token, and context:

```typescript
withOAuth({
  issuer: 'https://auth.example.com',
  verifyToken: async ({ request, bearerToken, context }) => {
    // Your token verification logic
    if (!bearerToken) {
      return undefined; // No token provided
    }
    
    try {
      const decoded = await verifyJWT(bearerToken);
      return {
        valid: true,
        user: decoded.user,
        scopes: decoded.scopes,
      };
    } catch (error) {
      return undefined; // Invalid token
    }
  }
})
```

***

## Token Verification

### JWT Verification Example

```typescript
import jwt from 'jsonwebtoken';

withOAuth({
  issuer: 'https://auth.example.com',
  verifyToken: async ({ bearerToken, context }) => {
    if (!bearerToken) {
      return undefined;
    }
    
    try {
      const decoded = jwt.verify(bearerToken, process.env.JWT_SECRET);
      
      // Additional validation
      if (decoded.exp < Date.now() / 1000) {
        return undefined; // Token expired
      }
      
      return {
        valid: true,
        user: {
          id: decoded.userId,
          email: decoded.email,
          roles: decoded.roles,
        },
        scopes: decoded.scopes || [],
      };
    } catch (error) {
      return undefined; // Invalid token
    }
  }
})
```

### Database Token Verification

```typescript
withOAuth({
  issuer: 'https://auth.example.com',
  verifyToken: async ({ bearerToken, context }) => {
    if (!bearerToken) {
      return undefined;
    }
    
    // Look up token in database
    const token = await context.context.db.accessToken.findUnique({
      where: { token: bearerToken },
      include: { user: true }
    });
    
    if (!token || token.expiresAt < new Date()) {
      return undefined; // Token not found or expired
    }
    
    return {
      valid: true,
      user: token.user,
      scopes: token.scopes,
    };
  }
})
```

***

## OAuth Metadata Endpoint

The adapter automatically exposes an OAuth protected resource metadata endpoint. You need to create a route for it:

**Next.js Route:**

```typescript
// src/app/.well-known/oauth-protected-resource/route.ts
import { auth } from '@/app/api/mcp/[...transport]/route';

export const GET = auth.resource;
export const OPTIONS = auth.cors;
```

**Express Route:**

```typescript
// Express example
app.get('/.well-known/oauth-protected-resource', auth.resource);
app.options('/.well-known/oauth-protected-resource', auth.cors);
```

***

## Protected Routes

Once OAuth is configured, all MCP requests require a valid Bearer token:

**Request Headers:**

```
Authorization: Bearer <your-token>
```

**Unprotected Request:**

```
GET /api/mcp/sse
// Returns 401 Unauthorized
```

**Protected Request:**

```
GET /api/mcp/sse
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
// Returns 200 OK with MCP response
```

***

## Accessing User Context

In your tool handlers, you can access the authenticated user from the context:

```typescript
.addTool({
  name: 'getMyProfile',
  description: 'Get my user profile',
  args: {},
  handler: async (args, context) => {
    // User is available in context if OAuth is enabled
    // Note: This requires additional setup to pass user from OAuth to context
    const user = context.context.user;
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(user, null, 2)
      }]
    };
  },
})
```

***

## Complete Example

Here's a complete example with OAuth and user context:

```typescript
import { IgniterMcpServer } from '@igniter-js/adapter-mcp-server';
import jwt from 'jsonwebtoken';

const { handler, auth } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .withOAuth({
    issuer: 'https://auth.example.com',
    resourceMetadataPath: '/.well-known/oauth-protected-resource',
    scopes: ['mcp:read', 'mcp:write'],
    verifyToken: async ({ bearerToken, context }) => {
      if (!bearerToken) {
        return undefined;
      }
      
      try {
        const decoded = jwt.verify(bearerToken, process.env.JWT_SECRET) as any;
        
        // You can inject the user into the router context
        // This requires modifying createMcpContext to include the user
        
        return {
          valid: true,
          user: {
            id: decoded.userId,
            email: decoded.email,
          },
          scopes: decoded.scopes || ['mcp:read'],
        };
      } catch (error) {
        return undefined;
      }
    }
  })
  .build();

export const GET = handler;
export const POST = handler;
export const OPTIONS = auth.cors;
```

***

## Error Responses

When authentication fails, the adapter returns proper OAuth error responses:

**401 Unauthorized:**

```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mcp-server", error="invalid_token"
```

**403 Forbidden (insufficient scopes):**

```
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="mcp-server", error="insufficient_scope", scope="mcp:write"
```

***

## Best Practices

### 1. Always Validate Tokens

Never trust tokens without verification:

```typescript
// ✅ Good
verifyToken: async ({ bearerToken }) => {
  if (!bearerToken) return undefined;
  return await verifyJWT(bearerToken);
}

// ❌ Bad
verifyToken: async ({ bearerToken }) => {
  return { valid: true }; // No validation!
}
```

### 2. Check Token Expiration

Always verify token expiration:

```typescript
verifyToken: async ({ bearerToken }) => {
  const decoded = await verifyJWT(bearerToken);
  if (decoded.exp < Date.now() / 1000) {
    return undefined; // Expired
  }
  return { valid: true, user: decoded.user };
}
```

### 3. Validate Scopes

Check required scopes for sensitive operations:

```typescript
verifyToken: async ({ bearerToken }) => {
  const decoded = await verifyJWT(bearerToken);
  const hasWriteScope = decoded.scopes?.includes('mcp:write');
  
  return {
    valid: true,
    user: decoded.user,
    scopes: decoded.scopes,
  };
}
```

### 4. Use Environment Variables

Store sensitive configuration in environment variables:

```typescript
withOAuth({
  issuer: process.env.OAUTH_ISSUER,
  verifyToken: async ({ bearerToken }) => {
    return await verifyJWT(bearerToken, process.env.JWT_SECRET);
  }
})
```

***

## Troubleshooting

### Token Not Validated

If tokens aren't being validated:

1. Check that `verifyToken` is properly implemented
2. Verify the Bearer token is being extracted correctly
3. Check token expiration and signature

### CORS Issues

If you encounter CORS issues:

1. Export the `auth.cors` handler as `OPTIONS`
2. Ensure CORS headers are properly set
3. Check browser console for CORS errors

### 401 Responses

If you're getting 401 responses:

1. Verify token format: `Bearer <token>`
2. Check token expiration
3. Verify token signature matches your secret
4. Check `verifyToken` implementation

***

## Next Steps

* Learn about [Event Handlers](/docs/mcp-server/events) for monitoring
* Explore [Advanced Configurations](/docs/mcp-server/advanced)
* Check out [Best Practices](/docs/mcp-server/best-practices)


---

# Prompts & Resources

> Use prompts and resources to provide AI agents with structured guidance and data access.
URL: https://igniterjs.com/docs/mcp-server/prompts-resources

## Overview

MCP supports two additional concepts beyond tools:

* **Prompts**: Pre-defined prompt templates that AI agents can use to guide interactions
* **Resources**: Read-only data sources that AI agents can access

***

## Prompts

Prompts are pre-defined message templates that help AI agents understand how to interact with your system. They're useful for:

* Debugging workflows
* Multi-step processes
* Complex instructions
* Context-aware guidance

***

## Adding Prompts

### Builder Pattern

```typescript
import { IgniterMcpServer } from '@igniter-js/adapter-mcp-server';
import { z } from 'zod';

const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .addPrompt({
    name: 'debugUser',
    description: 'Debug user account issues',
    args: {
      userId: z.string().uuid(),
    },
    handler: async (args, context) => {
      // context is automatically typed from your router!
      return {
        messages: [{
          role: 'user',
          content: {
            type: 'text',
            text: `Please debug the account for user ${args.userId}. ` +
                  `Check their permissions, recent activity, and any error logs. ` +
                  `If you find issues, use the appropriate tools to fix them.`
          }
        }]
      };
    },
  })
  .build();
```

### Function API

```typescript
import { createMcpAdapter } from '@igniter-js/adapter-mcp-server';
import { z } from 'zod';

const { server } = createMcpAdapter({
  router: AppRouter,
  prompts: {
    custom: [{
      name: 'debugUser',
      description: 'Debug user account issues',
      args: {
        userId: z.string().uuid(),
      },
      handler: async (args, context) => {
        return {
          messages: [{
            role: 'user',
            content: {
              type: 'text',
              text: `Debug user ${args.userId}`
            }
          }]
        };
      }
    }]
  }
});
```

***

## Prompt Structure

### Required Fields

**`name`** (string): Prompt name

**`description`** (string): Prompt description

**`args`** (ZodRawShape, optional): Arguments schema

**`handler`** (function): Function that returns prompt messages

***

## Prompt Handler

The handler returns an array of messages:

```typescript
handler: async (args, context) => {
  return {
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: 'Your prompt text here'
        }
      },
      // You can include multiple messages
      {
        role: 'assistant',
        content: {
          type: 'text',
          text: 'Previous context or response'
        }
      }
    ]
  };
}
```

***

## Practical Prompt Examples

### Example 1: Debugging Workflow

```typescript
.addPrompt({
  name: 'troubleshootOrder',
  description: 'Troubleshoot an order that failed to process',
  args: {
    orderId: z.string().uuid(),
  },
  handler: async (args, context) => {
    return {
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: `Order ${args.orderId} failed to process. ` +
                `Please investigate by:\n` +
                `1. Checking the order status using orders.getById\n` +
                `2. Reviewing payment information using payments.getByOrderId\n` +
                `3. Checking for error logs using logs.search with orderId filter\n` +
                `4. If payment failed, retry using payments.retry\n` +
                `5. Report findings and any actions taken`
        }
      }]
    };
  },
})
```

### Example 2: Multi-Step Analysis

```typescript
.addPrompt({
  name: 'analyzeUserActivity',
  description: 'Perform comprehensive user activity analysis',
  args: {
    userId: z.string().uuid(),
    dateRange: z.object({
      start: z.coerce.date(),
      end: z.coerce.date(),
    }),
  },
  handler: async (args, context) => {
    return {
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: `Analyze user ${args.userId}'s activity from ` +
                `${args.dateRange.start.toISOString()} to ` +
                `${args.dateRange.end.toISOString()}.\n\n` +
                `Steps:\n` +
                `1. Get user details with users.getById\n` +
                `2. Get activity logs with logs.getByUser for the date range\n` +
                `3. Get orders with orders.getByUser for the date range\n` +
                `4. Calculate metrics: total orders, total spent, most active day\n` +
                `5. Identify patterns or anomalies\n` +
                `6. Provide a summary report`
        }
      }]
    };
  },
})
```

***

## Resources

Resources are read-only data sources that AI agents can access. They're useful for:

* Configuration files
* Documentation
* Reference data
* Static content

***

## Adding Resources

### Builder Pattern

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .addResource({
    uri: 'config://app/settings',
    name: 'Application Settings',
    description: 'Current application configuration',
    mimeType: 'application/json',
    handler: async (context) => {
      // context is automatically typed!
      const settings = await getAppSettings();
      return {
        contents: [{
          uri: 'config://app/settings',
          mimeType: 'application/json',
          text: JSON.stringify(settings, null, 2)
        }]
      };
    }
  })
  .build();
```

### Function API

```typescript
const { server } = createMcpAdapter({
  router: AppRouter,
  resources: {
    custom: [{
      uri: 'config://app/settings',
      name: 'Application Settings',
      description: 'Current application configuration',
      mimeType: 'application/json',
      handler: async (context) => {
        const settings = await getAppSettings();
        return {
          contents: [{
            uri: 'config://app/settings',
            mimeType: 'application/json',
            text: JSON.stringify(settings, null, 2)
          }]
        };
      }
    }]
  }
});
```

***

## Resource Structure

### Required Fields

**`uri`** (string): Resource URI (use schemes like `config://`, `file://`, `db://`)

**`name`** (string): Resource name

**`description`** (string): Resource description

**`mimeType`** (string): MIME type of the resource content

**`handler`** (function): Function that returns resource contents

***

## Resource Handler

The handler returns resource contents:

```typescript
handler: async (context) => {
  // Fetch or generate resource content
  const content = await getResourceContent();
  
  return {
    contents: [{
      uri: 'config://app/settings',
      mimeType: 'application/json',
      text: JSON.stringify(content, null, 2)
    }]
  };
}
```

***

## Practical Resource Examples

### Example 1: Application Configuration

```typescript
.addResource({
  uri: 'config://app/settings',
  name: 'Application Settings',
  description: 'Current application configuration',
  mimeType: 'application/json',
  handler: async (context) => {
    const settings = {
      version: process.env.APP_VERSION,
      environment: process.env.NODE_ENV,
      features: {
        enableFeatureX: process.env.FEATURE_X === 'true',
        enableFeatureY: process.env.FEATURE_Y === 'true',
      },
      limits: {
        maxUsers: parseInt(process.env.MAX_USERS || '1000'),
        maxRequestsPerMinute: parseInt(process.env.MAX_RPM || '100'),
      }
    };
    
    return {
      contents: [{
        uri: 'config://app/settings',
        mimeType: 'application/json',
        text: JSON.stringify(settings, null, 2)
      }]
    };
  }
})
```

### Example 2: API Documentation

```typescript
.addResource({
  uri: 'docs://api/reference',
  name: 'API Reference',
  description: 'API endpoint documentation',
  mimeType: 'text/markdown',
  handler: async (context) => {
    const docs = `# API Reference

## Users Endpoints

### GET /users
List all users

### GET /users/:id
Get user by ID

### POST /users
Create a new user

## Products Endpoints

### GET /products
List all products

### GET /products/:id
Get product by ID
`;
    
    return {
      contents: [{
        uri: 'docs://api/reference',
        mimeType: 'text/markdown',
        text: docs
      }]
    };
  }
})
```

### Example 3: Database Schema

```typescript
.addResource({
  uri: 'db://schema/users',
  name: 'Users Table Schema',
  description: 'Database schema for users table',
  mimeType: 'application/json',
  handler: async (context) => {
    const schema = {
      table: 'users',
      columns: [
        { name: 'id', type: 'uuid', primaryKey: true },
        { name: 'email', type: 'varchar(255)', unique: true, nullable: false },
        { name: 'name', type: 'varchar(255)', nullable: false },
        { name: 'created_at', type: 'timestamp', default: 'now()' },
        { name: 'updated_at', type: 'timestamp', default: 'now()' },
      ],
      indexes: [
        { columns: ['email'], unique: true },
        { columns: ['created_at'] },
      ]
    };
    
    return {
      contents: [{
        uri: 'db://schema/users',
        mimeType: 'application/json',
        text: JSON.stringify(schema, null, 2)
      }]
    };
  }
})
```

***

## URI Schemes

Use consistent URI schemes for better organization:

* `config://` - Configuration resources
* `docs://` - Documentation resources
* `db://` - Database resources
* `file://` - File-based resources
* `api://` - API metadata resources

***

## Multiple Prompts and Resources

You can add multiple prompts and resources:

**Builder Pattern:**

```typescript
const { handler } = IgniterMcpServer
  .create()
  .router(AppRouter)
  .addPrompt({ /* prompt 1 */ })
  .addPrompt({ /* prompt 2 */ })
  .addResource({ /* resource 1 */ })
  .addResource({ /* resource 2 */ })
  .build();
```

**Function API:**

```typescript
const { server } = createMcpAdapter({
  router: AppRouter,
  prompts: {
    custom: [
      { /* prompt 1 */ },
      { /* prompt 2 */ },
    ]
  },
  resources: {
    custom: [
      { /* resource 1 */ },
      { /* resource 2 */ },
    ]
  }
});
```

***

## Best Practices

### 1. Clear Descriptions

Provide clear, actionable descriptions:

```typescript
// ✅ Good
{
  name: 'debugUser',
  description: 'Debug user account issues by checking permissions, activity logs, and recent errors',
}

// ❌ Bad
{
  name: 'debug',
  description: 'Debug stuff',
}
```

### 2. Use Schemas for Prompts

Even though prompts can be argument-less, use schemas when appropriate:

```typescript
args: {
  userId: z.string().uuid().describe('User ID to debug'),
  includeHistory: z.boolean().default(false).describe('Include full history'),
}
```

### 3. Keep Resources Updated

Resources should reflect current state:

```typescript
handler: async (context) => {
  // ✅ Fetch fresh data
  const settings = await getCurrentSettings();
  
  // ❌ Don't use stale cached data
  // const settings = cachedSettings;
  
  return { contents: [...] };
}
```

### 4. Use Appropriate MIME Types

Choose correct MIME types for resources:

* `application/json` - JSON data
* `text/markdown` - Markdown documentation
* `text/plain` - Plain text
* `application/xml` - XML data

***

## Next Steps

* Learn about [OAuth](/docs/mcp-server/oauth) for securing your server
* Explore [Event Handlers](/docs/mcp-server/events) for monitoring
* Check out [Best Practices](/docs/mcp-server/best-practices)


---

# Troubleshooting

> Diagnose common storage issues with adapters, URLs, policies, and permissions.
URL: https://igniterjs.com/docs/storage/troubleshooting

## Quick Checks

<Steps>
  <Step>
    ### Configuration - Is `IGNITER_STORAGE_URL` set and reachable? URLs are

    used to strip prefixes—mismatches cause `IGNITER_STORAGE_INVALID_PATH_HOST`.

    * Did you pick an adapter? Set `.withAdapter(...)` or
      `IGNITER_STORAGE_ADAPTER`.
  </Step>

  <Step>
    ### Permissions - S3: bucket exists, policy allows `s3:GetObject` and write

    access for your credentials. - GCS: service account has storage object
    admin/read roles for the bucket.
  </Step>

  <Step>
    ### Policies - Size/type violations throw

    `IGNITER_STORAGE_UPLOAD_POLICY_VIOLATION`. Confirm `contentType` inference
    or set it explicitly for streams.
  </Step>
</Steps>

## Common Errors

* `IGNITER_STORAGE_ADAPTER_NOT_CONFIGURED`: adapter key missing or factory not found. Check env and builder order.
* `IGNITER_STORAGE_INVALID_SCOPE` or `IGNITER_STORAGE_SCOPE_IDENTIFIER_REQUIRED`: scope key absent or identifier missing; review your `addScope` calls.
* `IGNITER_STORAGE_COPY_NOT_SUPPORTED` / `IGNITER_STORAGE_MOVE_NOT_SUPPORTED`: adapter lacks copy/move; fall back to download + upload.
* `IGNITER_STORAGE_FETCH_FAILED`: remote URL fetch failed during `uploadFromUrl`; verify URL and network.

## Logging and Telemetry

Enable hooks and telemetry to capture failing paths and durations. Error events include `storage.error.code` and `storage.error.message`, making dashboards actionable.

For the full list of codes, see [Error Codes](/docs/storage/\(reference\)/error-codes). If you need to change folder structures, review [Migrations & Cleanup](/docs/storage/\(guides\)/migrations-and-cleanup).


---

# Advanced

> Multi-tenant scopes, telemetry integration, custom serializers, and building your own adapters. Advanced patterns for production @igniter-js/store usage.
URL: https://igniterjs.com/docs/store/advanced

## Overview

This guide covers advanced `@igniter-js/store` features for production applications: multi-tenant isolation with scopes, observability via telemetry, custom serializers, and building custom adapters.

***

## Scopes — Multi-Tenant Isolation

Scopes automatically prefix all keys with tenant identifiers, providing data isolation without manual key management.

### Defining Scopes

```typescript
import { IgniterStore } from "@igniter-js/store";

const store = IgniterStore.create()
  .withAdapter(adapter)
  .withService("api")
  .addScope("organization", {
    required: true,
    description: "Organization tenant",
  })
  .addScope("workspace") // Optional, no description
  .build();
```

### Using Scoped Stores

```typescript
// Type-safe — only "organization" | "workspace" allowed
const orgStore = store.scope("organization", "org_123");

// All keys are automatically prefixed:
// igniter:store:api:organization:org_123:kv:{your-key}
await orgStore.kv.set("settings", { theme: "dark" });

// The scoped store has the same API as the root store
await orgStore.counter.increment("api-calls");
await orgStore.events.publish("user:created", { /* ... */ });
```

### Chained Scopes

```typescript
const scoped = store
  .scope("organization", "org_123")
  .scope("workspace", "ws_456");

// Key: igniter:store:api:organization:org_123:workspace:ws_456:kv:config
await scoped.kv.set("config", { feature: true });

// Works with all operations
const streamConsumer = scoped.streams.group("workers", "w-1");
await streamConsumer.ensure("events");
```

### Scope Validation

```typescript
const store = IgniterStore.create()
  .withAdapter(adapter)
  .withService("api")
  .addScope("organization") // Only "organization" is valid
  .build();

store.scope("organization", "org_1"); // ✅ OK
// store.scope("workspace", "ws_1");  // ❌ TypeScript error + runtime: STORE_INVALID_SCOPE_KEY
```

<Callout type="success" title="Best Practice">
  Define scopes with `addScope()` for type safety. Without definitions, any scope key is accepted at the TypeScript level, but you lose compile-time validation.
</Callout>

### Multi-Tenant Example: SaaS Pricing Cache

```typescript
const store = IgniterStore.create()
  .withAdapter(adapter)
  .withService("billing")
  .addScope("tenant_id", { required: true })
  .build();

// Per-request, scope to the current tenant
async function getProductPricing(tenantId: string, productId: string) {
  const tenantStore = store.scope("tenant_id", tenantId);
  const key = `product:${productId}:pricing`;

  let pricing = await tenantStore.kv.get(key);
  if (!pricing) {
    pricing = await db.pricing.findUnique({
      where: { tenantId, productId },
    });
    await tenantStore.kv.set(key, pricing, { ttl: 3600 });
  }

  return pricing;
}
```

***

## Telemetry Integration

`@igniter-js/store` emits typed telemetry events for every operation when you configure telemetry.

### Setup

```typescript
import { IgniterTelemetry } from "@igniter-js/telemetry";
import { IgniterStoreTelemetryEvents } from "@igniter-js/store/telemetry";
import { IgniterStore } from "@igniter-js/store";

// 1. Create telemetry manager with store events
const telemetry = IgniterTelemetry.create()
  .withService("api")
  .addEvents(IgniterStoreTelemetryEvents)
  .withRedaction({
    denylistKeys: ["value", "message", "payload", "data"],
    hashKeys: ["ctx.store.key"],
  })
  .build();

// 2. Wire into store
const store = IgniterStore.create()
  .withAdapter(adapter)
  .withService("api")
  .withTelemetry(telemetry)
  .build();
```

### Telemetry Events Emitted

| Event                               | Trigger                               |
| ----------------------------------- | ------------------------------------- |
| `igniter.store.kv.get.started`      | `store.kv.get()` called               |
| `igniter.store.kv.get.success`      | `store.kv.get()` succeeds             |
| `igniter.store.kv.get.error`        | `store.kv.get()` fails                |
| `igniter.store.kv.set.*`            | `store.kv.set()` lifecycle            |
| `igniter.store.counter.increment.*` | `store.counter.increment()` lifecycle |
| `igniter.store.claim.acquire.*`     | `store.claim.once()` lifecycle        |
| `igniter.store.batch.get.*`         | `store.batch.get()` lifecycle         |
| `igniter.store.events.publish.*`    | `store.events.publish()` lifecycle    |
| `igniter.store.stream.append.*`     | `store.streams.append()` lifecycle    |
| `igniter.store.dev.scan.*`          | `store.dev.scan()` lifecycle          |

### Event Attributes

Every event includes:

```typescript
{
  "ctx.store.service": "api",           // Service name
  "ctx.store.namespace": "kv",          // Operation namespace
  "ctx.store.scope_key": "organization", // Scope type (if scoped)
  "ctx.store.scope_depth": 2,           // Scope chain depth
}
```

<Callout type="warn" title="Redaction is critical">
  Telemetry events may contain key names. Always configure `withRedaction()` to hash or deny-list sensitive fields like `key`, `value`, and `message`. The recommended configuration:

  ```typescript
  .withRedaction({
    denylistKeys: ["value", "message", "payload", "data"],
    hashKeys: ["ctx.store.key"],
  })
  ```
</Callout>

***

## Custom Serializer

By default, the Redis adapter uses `JSON.stringify`/`JSON.parse`. Provide a custom serializer for MessagePack or other formats:

```typescript
import { encode, decode } from "@msgpack/msgpack";

const store = IgniterStore.create()
  .withAdapter(adapter)
  .withService("api")
  .withSerializer({
    encode: (value: unknown): string =>
      Buffer.from(encode(value)).toString("base64"),
    decode: (value: string): unknown =>
      decode(Buffer.from(value, "base64")),
  })
  .build();
```

### Serializer Interface

```typescript
interface IgniterStoreSerializer {
  encode(value: unknown): string;
  decode(value: string): unknown;
}
```

***

## Adapters

### Redis Adapter (Production)

```typescript
import { IgniterStoreRedisAdapter } from "@igniter-js/store/adapters";
import Redis from "ioredis";

const redis = new Redis(process.env.REDIS_URL);
const adapter = IgniterStoreRedisAdapter.create({ redis });
```

The Redis adapter internally creates a **duplicate client** for Pub/Sub subscriptions (Redis requirement). Your main client stays dedicated to commands.

### Memory Adapter (Testing & Desktop)

```typescript
import { IgniterStoreMemoryAdapter } from "@igniter-js/store/adapters";

const adapter = IgniterStoreMemoryAdapter.create();

// Supports: kv, counter, claim, batch, pub/sub, streams, scan
// Ideal for: unit tests, Electron apps, Tauri apps, CI pipelines
```

### Building a Custom Adapter

Implement the `IgniterStoreAdapter` interface:

```typescript
import type { IgniterStoreAdapter, IgniterStoreBatchEntry } from "@igniter-js/store";

class CustomAdapter implements IgniterStoreAdapter<MyClient> {
  client: MyClient;

  constructor(client: MyClient) {
    this.client = client;
  }

  // Required: Key-Value
  async get<T>(key: string): Promise<T | null> { /* ... */ }
  async set(key: string, value: unknown, options?: { ttl?: number }): Promise<void> { /* ... */ }
  async delete(key: string): Promise<void> { /* ... */ }
  async has(key: string): Promise<boolean> { /* ... */ }

  // Required: Atomic
  async increment(key: string, delta?: number): Promise<number> { /* ... */ }
  async expire(key: string, ttl: number): Promise<void> { /* ... */ }
  async setNX(key: string, value: unknown, options?: { ttl?: number }): Promise<boolean> { /* ... */ }

  // Required: Batch
  async mget<T>(keys: string[]): Promise<(T | null)[]> { /* ... */ }
  async mset(entries: IgniterStoreBatchEntry[]): Promise<void> { /* ... */ }

  // Required: Pub/Sub
  async publish(channel: string, message: unknown): Promise<void> { /* ... */ }
  async subscribe(channel: string, callback: (msg: unknown) => void | Promise<void>): Promise<void> { /* ... */ }
  async unsubscribe(channel: string, callback?: (msg: unknown) => void | Promise<void>): Promise<void> { /* ... */ }

  // Required: Scan
  async scan(pattern: string, options?: { cursor?: string; count?: number }): Promise<{ keys: string[]; cursor: string }> { /* ... */ }

  // Required: Streams
  async xadd(stream: string, message: unknown, options?: { maxLen?: number; approximate?: boolean }): Promise<string> { /* ... */ }
  async xgroupCreate(stream: string, group: string, startId?: string): Promise<void> { /* ... */ }
  async xreadgroup<T>(stream: string, group: string, consumer: string, options?: { count?: number; blockMs?: number }): Promise<Array<{ id: string; message: T }>> { /* ... */ }
  async xrange<T>(stream: string, options?: { startId?: string; endId?: string; count?: number }): Promise<Array<{ id: string; message: T }>> { /* ... */ }
  async xrevrange<T>(stream: string, options?: { startId?: string; endId?: string; count?: number }): Promise<Array<{ id: string; message: T }>> { /* ... */ }
  async xack(stream: string, group: string, ids: string[]): Promise<void> { /* ... */ }
}
```

***

## Logger Integration

```typescript
const store = IgniterStore.create()
  .withAdapter(adapter)
  .withService("api")
  .withLogger({
    info: (msg, meta) => console.log(`[INFO] ${msg}`, meta),
    warn: (msg, meta) => console.warn(`[WARN] ${msg}`, meta),
    error: (msg, meta) => console.error(`[ERROR] ${msg}`, meta),
    debug: (msg, meta) => console.debug(`[DEBUG] ${msg}`, meta),
  })
  .build();

// Access logger from the store instance
store.logger?.info("Store initialized");
```

***

## Framework Integration

### Next.js (App Router)

```typescript
// lib/store.ts
import { IgniterStore } from "@igniter-js/store";
import { IgniterStoreRedisAdapter } from "@igniter-js/store/adapters";
import Redis from "ioredis";

const redis = new Redis(process.env.REDIS_URL!);

export const store = IgniterStore.create()
  .withAdapter(IgniterStoreRedisAdapter.create({ redis }))
  .withService("next-app")
  .build();

// app/api/users/[id]/route.ts
import { NextResponse } from "next/server";
import { store } from "@/lib/store";

export async function GET(_: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const user = await store.kv.get(`user:${id}`);

  if (!user) {
    return NextResponse.json({ error: "Not found" }, { status: 404 });
  }

  return NextResponse.json({ user });
}
```

### Express

```typescript
import express from "express";
import { store } from "./store";

const app = express();

app.get("/users/:id", async (req, res) => {
  const user = await store.kv.get(`user:${req.params.id}`);
  res.json({ user });
});

app.listen(3000);
```

### Fastify

```typescript
import Fastify from "fastify";
import { store } from "./store";

const app = Fastify();

app.get("/users/:id", async (req) => {
  const user = await store.kv.get(`user:${(req.params as any).id}`);
  return { user };
});

await app.listen({ port: 3000 });
```

***

## Next Steps

* Browse the complete [API reference](/docs/store/api-reference)
* See [troubleshooting](/docs/store/troubleshooting) for common errors
* Read the [package README](https://github.com/igniter-js/igniter-js/blob/main/packages/store/README.md) for exhaustive examples


---

# API Reference

> Complete API reference for @igniter-js/store. All builder methods, manager namespaces, event types, adapter interfaces, and error codes.
URL: https://igniterjs.com/docs/store/api-reference

## Overview

This document provides the complete API reference for `@igniter-js/store`. Every method and type documented here reflects the actual implementation.

***

## IgniterStore — Builder

The entry point is `IgniterStore.create()` which returns an `IgniterStoreBuilder`.

### `static create()`

Creates a new builder instance.

```typescript
const builder = IgniterStore.create();
```

### `withAdapter(adapter)`

Sets the storage adapter. **Required.**

| Parameter | Type                  | Description          |
| --------- | --------------------- | -------------------- |
| `adapter` | `IgniterStoreAdapter` | The adapter instance |

```typescript
.withAdapter(IgniterStoreRedisAdapter.create({ redis }))
```

### `withService(service)`

Sets the service name for key prefix isolation. **Required.**

| Parameter | Type     | Description                              |
| --------- | -------- | ---------------------------------------- |
| `service` | `string` | Service name (e.g., `"api"`, `"worker"`) |

```typescript
.withService("my-api")
```

### `withSerializer(serializer)`

Sets a custom serializer.

| Parameter    | Type                     | Description                       |
| ------------ | ------------------------ | --------------------------------- |
| `serializer` | `IgniterStoreSerializer` | Object with `encode` and `decode` |

```typescript
.withSerializer({
  encode: (value) => JSON.stringify(value),
  decode: (value) => JSON.parse(value),
})
```

### `withLogger(logger)`

Sets a logger instance.

| Parameter | Type            | Description                                  |
| --------- | --------------- | -------------------------------------------- |
| `logger`  | `IgniterLogger` | Logger with `info`, `warn`, `error`, `debug` |

### `withTelemetry(telemetry)`

Sets the telemetry manager for observability.

| Parameter   | Type                           | Description                                     |
| ----------- | ------------------------------ | ----------------------------------------------- |
| `telemetry` | `IgniterTelemetryManager<any>` | Telemetry instance from `@igniter-js/telemetry` |

### `addScope(key, options?)`

Adds a typed scope definition.

| Parameter             | Type       | Description                                 |
| --------------------- | ---------- | ------------------------------------------- |
| `key`                 | `string`   | Scope key (e.g., `"organization"`)          |
| `options.required`    | `boolean?` | Whether scope is required (default: `true`) |
| `options.description` | `string?`  | Human-readable description                  |

```typescript
.addScope("organization", { required: true, description: "Tenant org" })
.addScope("workspace")
```

### `addEvents(events, validation?)`

Adds typed events for a namespace.

| Parameter                           | Type                    | Description                                      |
| ----------------------------------- | ----------------------- | ------------------------------------------------ |
| `events`                            | `{ namespace, events }` | Built with `IgniterStoreEvents.create().build()` |
| `validation.validatePublish`        | `boolean?`              | Validate when publishing (default: `true`)       |
| `validation.validateSubscribe`      | `boolean?`              | Validate when subscribing (default: `false`)     |
| `validation.throwOnValidationError` | `boolean?`              | Throw on invalid payload (default: `true`)       |

```typescript
.addEvents(UserEvents, {
  validatePublish: true,
  validateSubscribe: false,
  throwOnValidationError: true,
})
```

### `build()`

Builds and returns the `IgniterStoreManager` instance.

```typescript
const store = builder.build();
```

***

## IgniterStoreManager

The runtime store instance returned by `.build()`.

### Namespaced Operations

| Property        | Type                         | Purpose                       |
| --------------- | ---------------------------- | ----------------------------- |
| `store.kv`      | `IgniterStoreKV`             | Key-value operations          |
| `store.counter` | `IgniterStoreCounter`        | Atomic counters               |
| `store.claim`   | `IgniterStoreClaim`          | Distributed claims (locks)    |
| `store.batch`   | `IgniterStoreBatch`          | Multi-key operations          |
| `store.events`  | `IgniterStoreEventsManager`  | Pub/Sub (string + proxy APIs) |
| `store.streams` | `IgniterStoreStreams`        | Redis Streams                 |
| `store.dev`     | `IgniterStoreDev`            | Development/debugging tools   |
| `store.logger`  | `IgniterLogger \| undefined` | Logger instance               |

### `scope(scopeKey, identifier)`

Creates a scoped store instance.

| Parameter    | Type               | Description                                       |
| ------------ | ------------------ | ------------------------------------------------- |
| `scopeKey`   | `string`           | Scope key (type-safe if defined via `addScope()`) |
| `identifier` | `string \| number` | Scope identifier                                  |

Returns: `IgniterStoreManager` — a new scoped instance with auto-prefixed keys.

***

## Key-Value (`store.kv`)

### `get<T>(key)`

Retrieves a value.

| Parameter | Type     | Description         |
| --------- | -------- | ------------------- |
| `key`     | `string` | The key to retrieve |

Returns: `Promise<T | null>`

```typescript
const user = await store.kv.get<User>("user:123");
```

### `set(key, value, options?)`

Stores a value.

| Parameter     | Type      | Description                   |
| ------------- | --------- | ----------------------------- |
| `key`         | `string`  | The key                       |
| `value`       | `unknown` | The value (JSON-serializable) |
| `options.ttl` | `number?` | TTL in seconds                |

Returns: `Promise<void>`

```typescript
await store.kv.set("user:123", { name: "Avery" }, { ttl: 3600 });
```

### `remove(key)`

Deletes a key.

| Parameter | Type     | Description       |
| --------- | -------- | ----------------- |
| `key`     | `string` | The key to delete |

Returns: `Promise<void>`

### `exists(key)`

Checks if a key exists.

| Parameter | Type     | Description      |
| --------- | -------- | ---------------- |
| `key`     | `string` | The key to check |

Returns: `Promise<boolean>`

### `expire(key, ttlSeconds)`

Sets a TTL on an existing key.

| Parameter    | Type     | Description    |
| ------------ | -------- | -------------- |
| `key`        | `string` | The key        |
| `ttlSeconds` | `number` | TTL in seconds |

Returns: `Promise<void>`

### `touch(key, ttlSeconds)`

Updates a key's TTL (like `expire`, signals access).

| Parameter    | Type     | Description    |
| ------------ | -------- | -------------- |
| `key`        | `string` | The key        |
| `ttlSeconds` | `number` | TTL in seconds |

Returns: `Promise<void>`

***

## Counter (`store.counter`)

### `increment(key)`

Atomically increments a counter.

| Parameter | Type     | Description     |
| --------- | -------- | --------------- |
| `key`     | `string` | The counter key |

Returns: `Promise<number>` — new value after increment

```typescript
const views = await store.counter.increment("page-views"); // → 1
```

### `decrement(key)`

Atomically decrements a counter.

| Parameter | Type     | Description     |
| --------- | -------- | --------------- |
| `key`     | `string` | The counter key |

Returns: `Promise<number>` — new value after decrement

```typescript
const remaining = await store.counter.decrement("stock"); // → -1
```

### `expire(key, ttlSeconds)`

Sets TTL on a counter.

| Parameter    | Type     | Description     |
| ------------ | -------- | --------------- |
| `key`        | `string` | The counter key |
| `ttlSeconds` | `number` | TTL in seconds  |

Returns: `Promise<void>`

***

## Claim (`store.claim`)

### `once(key, value, options?)`

Acquires a distributed lock using SETNX.

| Parameter     | Type      | Description                 |
| ------------- | --------- | --------------------------- |
| `key`         | `string`  | The claim key               |
| `value`       | `unknown` | Owner identifier            |
| `options.ttl` | `number?` | Auto-expire after N seconds |

Returns: `Promise<boolean>` — `true` if acquired, `false` if already held

```typescript
const claimed = await store.claim.once("job:cleanup", "worker-1", { ttl: 30 });
```

***

## Batch (`store.batch`)

### `get<T>(keys)`

Retrieves multiple values.

| Parameter | Type       | Description   |
| --------- | ---------- | ------------- |
| `keys`    | `string[]` | Array of keys |

Returns: `Promise<(T | null)[]>` — values in same order, `null` for missing

```typescript
const users = await store.batch.get<User>(["user:1", "user:2", "user:3"]);
```

### `set(entries)`

Stores multiple values.

| Parameter | Type                                                   | Description       |
| --------- | ------------------------------------------------------ | ----------------- |
| `entries` | `Array<{ key: string; value: unknown; ttl?: number }>` | Key-value entries |

Returns: `Promise<void>`

```typescript
await store.batch.set([
  { key: "user:1", value: { name: "Alice" }, ttl: 3600 },
  { key: "user:2", value: { name: "Bob" } },
]);
```

***

## Events (`store.events`)

`store.events` exposes both string-based and proxy-based APIs.

### String-Based API

**`publish(event, message)`**

| Parameter | Type     | Description                         |
| --------- | -------- | ----------------------------------- |
| `event`   | `string` | Event name (e.g., `"user:created"`) |
| `message` | (typed)  | Payload (typed from schema)         |

Returns: `Promise<void>`

**`subscribe(event, handler)`**

| Parameter | Type                                                       | Description                                |
| --------- | ---------------------------------------------------------- | ------------------------------------------ |
| `event`   | `string`                                                   | Event name or wildcard (`"user:*"`, `"*"`) |
| `handler` | `(ctx: IgniterStoreEventContext) => void \| Promise<void>` | Callback                                   |

Returns: `Promise<IgniterStoreUnsubscribeFn>`

### Proxy-Based API

For each registered event, `store.events.namespace.eventName` provides:

**`.publish(message)`** — Publish a message (typed).

**`.subscribe(handler)`** — Subscribe to the event (typed context). Returns unsubscribe function.

### IgniterStoreEventContext

| Field       | Type                                  | Description             |
| ----------- | ------------------------------------- | ----------------------- |
| `type`      | `string`                              | Full event name         |
| `data`      | `TPayload`                            | Event payload           |
| `timestamp` | `string`                              | ISO 8601 timestamp      |
| `scope?`    | `{ key: string; identifier: string }` | Current scope if scoped |

***

## Streams (`store.streams`)

### `append(stream, message, options?)`

Appends to a stream.

| Parameter             | Type       | Description         |
| --------------------- | ---------- | ------------------- |
| `stream`              | `string`   | Stream name         |
| `message`             | `unknown`  | Message payload     |
| `options.maxLen`      | `number?`  | Max stream length   |
| `options.approximate` | `boolean?` | Use \~ for trimming |

Returns: `Promise<string>` — message ID

### `group(group, consumer)`

Creates a consumer in a consumer group.

| Parameter  | Type     | Description   |
| ---------- | -------- | ------------- |
| `group`    | `string` | Group name    |
| `consumer` | `string` | Consumer name |

Returns: `IgniterStoreStreamConsumerGroup`

**Consumer Group Methods:**

* **`ensure(stream, options?)`** — Create group (idempotent)
* **`read<T>(stream, options?)`** — Read messages
* **`ack(stream, ids)`** — Acknowledge messages

### `range<T>(stream, options?)`

Reads a range of messages.

| Parameter         | Type       | Description               |
| ----------------- | ---------- | ------------------------- |
| `stream`          | `string`   | Stream name               |
| `options.startId` | `string?`  | Start ID (default: `"-"`) |
| `options.endId`   | `string?`  | End ID (default: `"+"`)   |
| `options.count`   | `number?`  | Max messages              |
| `options.reverse` | `boolean?` | Reverse order             |

Returns: `Promise<IgniterStoreStreamMessage<T>[]>`

***

## Dev Tools (`store.dev`)

### `scan(pattern, options?)`

Scans keys matching a pattern.

| Parameter        | Type      | Description                        |
| ---------------- | --------- | ---------------------------------- |
| `pattern`        | `string`  | Pattern (e.g., `"user:*"`)         |
| `options.cursor` | `string?` | Pagination cursor (default: `"0"`) |
| `options.count`  | `number?` | Keys per iteration (default: 10)   |

Returns: `Promise<{ keys: string[]; cursor: string }>`

```typescript
const { keys, cursor } = await store.dev.scan("user:*", { count: 100 });
```

***

## IgniterStoreEvents

### `static create(namespace)`

Creates a new events builder for a namespace.

| Parameter   | Type     | Description                       |
| ----------- | -------- | --------------------------------- |
| `namespace` | `string` | Unique namespace (e.g., `"user"`) |

### `event(name, schema)`

Adds an event with a Zod/StandardSchemaV1 schema.

| Parameter | Type               | Description                 |
| --------- | ------------------ | --------------------------- |
| `name`    | `string`           | Event name (no dots/colons) |
| `schema`  | `StandardSchemaV1` | Zod schema for the payload  |

### `group(name, builder)`

Creates a nested group of events.

| Parameter | Type                                                                        | Description           |
| --------- | --------------------------------------------------------------------------- | --------------------- |
| `name`    | `string`                                                                    | Group name (prefix)   |
| `builder` | `(group: IgniterStoreEventsGroupBuilder) => IgniterStoreEventsGroupBuilder` | Group config function |

### `build()`

Returns the events descriptor for `addEvents()`.

Returns: `{ namespace: string; events: IgniterStoreEventsDirectory }`

***

## Adapters

### IgniterStoreRedisAdapter

```typescript
import { IgniterStoreRedisAdapter } from "@igniter-js/store/adapters";

IgniterStoreRedisAdapter.create({ redis: Redis })
```

| Option  | Type    | Description             |
| ------- | ------- | ----------------------- |
| `redis` | `Redis` | ioredis client instance |

### IgniterStoreMemoryAdapter

```typescript
import { IgniterStoreMemoryAdapter } from "@igniter-js/store/adapters";

IgniterStoreMemoryAdapter.create()
```

No constructor options. Supports all operations including streams.

***

## Error Codes

All errors extend `IgniterStoreError` (which extends `IgniterError`).

### Configuration Errors

| Code                          | Message                     |
| ----------------------------- | --------------------------- |
| `STORE_ADAPTER_REQUIRED`      | Adapter not configured      |
| `STORE_SERVICE_REQUIRED`      | Service name not configured |
| `STORE_CONFIGURATION_INVALID` | Invalid configuration       |

### Scope Errors

| Code                              | Message                      |
| --------------------------------- | ---------------------------- |
| `STORE_SCOPE_KEY_REQUIRED`        | Scope key is required        |
| `STORE_SCOPE_IDENTIFIER_REQUIRED` | Scope identifier is required |
| `STORE_INVALID_SCOPE_KEY`         | Scope key not defined        |
| `STORE_DUPLICATE_SCOPE`           | Scope already defined        |

### Namespace & Event Errors

| Code                        | Message                      |
| --------------------------- | ---------------------------- |
| `STORE_MISSING_NAMESPACE`   | Events namespace required    |
| `STORE_INVALID_NAMESPACE`   | Invalid namespace format     |
| `STORE_RESERVED_NAMESPACE`  | Reserved prefix used         |
| `STORE_DUPLICATE_NAMESPACE` | Namespace already registered |
| `STORE_INVALID_EVENT_NAME`  | Invalid event name           |
| `STORE_DUPLICATE_EVENT`     | Event/group already defined  |

### Schema Errors

| Code                             | Message                       |
| -------------------------------- | ----------------------------- |
| `STORE_SCHEMA_VALIDATION_FAILED` | Payload doesn't match schema  |
| `STORE_SCHEMA_CHANNEL_NOT_FOUND` | Channel not found in registry |

### Operation Errors

| Code                     | Message                   |
| ------------------------ | ------------------------- |
| `STORE_OPERATION_FAILED` | Generic operation failure |
| `STORE_GET_FAILED`       | Get operation failed      |
| `STORE_SET_FAILED`       | Set operation failed      |
| `STORE_DELETE_FAILED`    | Delete operation failed   |
| `STORE_INCREMENT_FAILED` | Increment failed          |
| `STORE_PUBLISH_FAILED`   | Publish failed            |
| `STORE_SUBSCRIBE_FAILED` | Subscribe failed          |

### Batch Errors

| Code                           | Message                   |
| ------------------------------ | ------------------------- |
| `STORE_BATCH_FAILED`           | Batch operation failed    |
| `STORE_BATCH_KEYS_REQUIRED`    | Keys array is required    |
| `STORE_BATCH_ENTRIES_REQUIRED` | Entries array is required |

### Claim Errors

| Code                 | Message                |
| -------------------- | ---------------------- |
| `STORE_CLAIM_FAILED` | Claim operation failed |

### Stream Errors

| Code                               | Message                |
| ---------------------------------- | ---------------------- |
| `STORE_STREAM_APPEND_FAILED`       | Stream append failed   |
| `STORE_STREAM_READ_FAILED`         | Stream read failed     |
| `STORE_STREAM_GROUP_CREATE_FAILED` | Group creation failed  |
| `STORE_STREAM_ACK_FAILED`          | Acknowledgment failed  |
| `STORE_STREAM_NAME_REQUIRED`       | Stream name required   |
| `STORE_STREAM_GROUP_REQUIRED`      | Group name required    |
| `STORE_STREAM_CONSUMER_REQUIRED`   | Consumer name required |

### Serialization Errors

| Code                           | Message                      |
| ------------------------------ | ---------------------------- |
| `STORE_SERIALIZATION_FAILED`   | Value serialization failed   |
| `STORE_DESERIALIZATION_FAILED` | Value deserialization failed |

### Connection Errors

| Code                      | Message                  |
| ------------------------- | ------------------------ |
| `STORE_CONNECTION_FAILED` | Connection failed        |
| `STORE_NOT_CONNECTED`     | Not connected to backend |

### Error Handling

```typescript
import { IgniterStoreError } from "@igniter-js/store";

try {
  await store.kv.get("key");
} catch (error) {
  if (IgniterStoreError.is(error)) {
    console.log(error.code);     // e.g., "STORE_GET_FAILED"
    console.log(error.message);  // Human-readable message
    console.log(error.statusCode); // HTTP status code
  }
}
```

***

## Telemetry

### IgniterStoreTelemetryEvents

```typescript
import { IgniterStoreTelemetryEvents } from "@igniter-js/store/telemetry";
```

Returns a typed events registry for `@igniter-js/telemetry`. Use with:

```typescript
const telemetry = IgniterTelemetry.create()
  .withService("api")
  .addEvents(IgniterStoreTelemetryEvents)
  .build();
```

Events span every operation namespace: `igniter.store.kv.*`, `igniter.store.counter.*`, `igniter.store.batch.*`, `igniter.store.claim.*`, `igniter.store.events.*`, `igniter.store.stream.*`, `igniter.store.dev.*`.

***

## Next Steps

* See [troubleshooting](/docs/store/troubleshooting) for common errors
* Explore [advanced patterns](/docs/store/advanced) for production usage
* Read the [package README](https://github.com/igniter-js/igniter-js/blob/main/packages/store/README.md) for exhaustive real-world examples


---

# Counters, Claims & Batch

> Atomic counters, distributed claims (locks), batch operations, and dev tools. Build rate limiters, leader election, and bulk operations with store.counter, store.claim, store.batch, and store.dev.
URL: https://igniterjs.com/docs/store/atomic-operations

## Overview

Beyond key-value storage, `@igniter-js/store` provides atomic operations for counters, distributed claims (locks), batch reads/writes, and dev utilities for scanning keys.

| Namespace       | Purpose                    | Backed by                  |
| --------------- | -------------------------- | -------------------------- |
| `store.counter` | Atomic increment/decrement | `INCR` / `DECR`            |
| `store.claim`   | Distributed locks          | `SETNX`                    |
| `store.batch`   | Multi-key get/set          | `MGET` / `MSET` / Pipeline |
| `store.dev`     | Debugging & scanning       | `SCAN`                     |

***

## Counters (`store.counter`)

### Increment

Atomically increments a numeric counter. If the key doesn't exist, it's initialized to 0 before incrementing.

```typescript
const views = await store.counter.increment("page-views");
// First call → 1, second call → 2, third → 3 ...
```

### Decrement

```typescript
const remaining = await store.counter.decrement("available-slots");
// First call → -1, second call → -2 ...
```

### Counter with TTL

Set expiration on counters for periodic resets:

```typescript
const count = await store.counter.increment("daily-views");
if (count === 1) {
  // First hit of the day — set 24h expiration
  await store.counter.expire("daily-views", 86400);
}
```

***

## Rate Limiting

Build a rate limiter in a few lines:

```typescript
async function checkRateLimit(
  identifier: string,
  limit: number,
  windowSeconds: number,
): Promise<{ allowed: boolean; remaining: number }> {
  const key = `rate:${identifier}`;
  const count = await store.counter.increment(key);

  if (count === 1) {
    await store.counter.expire(key, windowSeconds);
  }

  if (count > limit) {
    return { allowed: false, remaining: 0 };
  }

  return { allowed: true, remaining: limit - count };
}

// Usage — 100 requests per 60 seconds per IP
const { allowed, remaining } = await checkRateLimit(req.ip, 100, 60);
if (!allowed) {
  throw new Error("Rate limit exceeded");
}
```

### Sliding Window Rate Limiting

For more precise limiting:

```typescript
async function slidingWindowRateLimit(
  identifier: string,
  limit: number,
  windowSeconds: number,
) {
  const now = Date.now();
  const windowKey = Math.floor(now / (windowSeconds * 1000));
  const key = `rate:sliding:${identifier}:${windowKey}`;

  const currentCount = await store.counter.increment(key);
  if (currentCount === 1) {
    await store.counter.expire(key, windowSeconds * 2);
  }

  // Check previous window
  const prevKey = `rate:sliding:${identifier}:${windowKey - 1}`;
  const prevCount = await store.kv.get<number>(prevKey) ?? 0;

  // Weighted count
  const weight = (now % (windowSeconds * 1000)) / (windowSeconds * 1000);
  const total = currentCount + prevCount * (1 - weight);

  return {
    allowed: total <= limit,
    remaining: Math.max(0, Math.floor(limit - total)),
  };
}
```

***

## Claims — Distributed Locks (`store.claim`)

`store.claim.once()` uses `SETNX` to atomically acquire a lock. Returns `true` if acquired, `false` if already held.

```typescript
const claimed = await store.claim.once(
  "job:cleanup",        // Lock key
  "worker-1",           // Owner identifier
  { ttl: 30 }           // Auto-expire after 30 seconds
);

if (claimed) {
  try {
    await performCleanup();
  } finally {
    await store.kv.remove("job:cleanup"); // Release
  }
}
```

### Leader Election for Cron Jobs

```typescript
async function runCronJob(jobName: string, fn: () => Promise<void>) {
  const lockKey = `cron:${jobName}`;
  const isLeader = await store.claim.once(lockKey, process.env.HOSTNAME!, { ttl: 55 });

  if (!isLeader) {
    console.log(`[${jobName}] Another instance is running. Skipping.`);
    return;
  }

  try {
    await fn();
  } finally {
    await store.kv.remove(lockKey);
  }
}

// Usage — only one instance runs this per minute
setInterval(() => runCronJob("cleanup", performCleanup), 60_000);
```

### Job Deduplication

```typescript
async function processJobOnce(jobId: string, fn: () => Promise<void>) {
  const key = `job:processed:${jobId}`;
  const acquired = await store.claim.once(key, "processor", { ttl: 86400 });

  if (!acquired) {
    return; // Already processed
  }

  await fn();
}
```

***

## Batch Operations (`store.batch`)

### Batch Get

```typescript
const users = await store.batch.get<User>([
  "user:1",
  "user:2",
  "user:3",
]);

// users = [User | null, User | null, User | null]
// null for missing keys
```

### Batch Set

```typescript
await store.batch.set([
  { key: "user:1", value: { name: "Alice" }, ttl: 3600 },
  { key: "user:2", value: { name: "Bob" }, ttl: 3600 },
  { key: "user:3", value: { name: "Charlie" } },
]);
```

<Callout type="success" title="Performance">
  Batch operations use Redis `MGET`/`MSET` or pipelines under the hood, drastically reducing round-trips compared to individual calls.
</Callout>

### Cache Warming

```typescript
async function warmPopularUsersCache(userIds: string[]) {
  const users = await db.user.findMany({
    where: { id: { in: userIds } },
  });

  await store.batch.set(
    users.map((user) => ({
      key: `user:${user.id}`,
      value: user,
      ttl: 3600,
    }))
  );
}
```

***

## Dev Tools (`store.dev`)

### Scanning Keys

```typescript
// Scan all user keys
const result = await store.dev.scan("user:*");
console.log(result.keys);  // ["user:1", "user:2", ...]
console.log(result.cursor); // "0" if scan is complete

// Paginated scan
let cursor = "0";
do {
  const { keys, cursor: nextCursor } = await store.dev.scan("user:*", {
    cursor,
    count: 100,
  });
  console.log("Found:", keys);
  cursor = nextCursor;
} while (cursor !== "0");
```

### Cleaning Up by Pattern

```typescript
async function deleteByPattern(pattern: string) {
  let cursor = "0";
  do {
    const result = await store.dev.scan(pattern, { cursor, count: 100 });
    for (const key of result.keys) {
      await store.kv.remove(key);
    }
    cursor = result.cursor;
  } while (cursor !== "0");
}

// Delete all cache keys for a tenant
await deleteByPattern("igniter:store:api:organization:org_123:*");
```

***

## Real-World Examples

### Request Counter per Endpoint

```typescript
async function trackEndpointHit(endpoint: string) {
  const today = new Date().toISOString().split("T")[0];
  const key = `metrics:${endpoint}:${today}`;

  const count = await store.counter.increment(key);
  if (count === 1) {
    // Expire at midnight
    const tomorrow = new Date();
    tomorrow.setDate(tomorrow.getDate() + 1);
    tomorrow.setHours(0, 0, 0, 0);
    const ttl = Math.floor((tomorrow.getTime() - Date.now()) / 1000);
    await store.counter.expire(key, ttl);
  }

  return count;
}
```

### Inventory Reservation

```typescript
async function reserveInventory(productId: string, quantity: number) {
  const key = `inventory:${productId}`;
  const available = await store.counter.decrement(key);

  if (available < 0) {
    // Rollback — not enough stock
    await store.counter.increment(key);
    throw new Error("Insufficient inventory");
  }

  return available;
}
```

### Feature Flag with Percentage Rollout

```typescript
async function isInRolloutGroup(
  feature: string,
  userId: string,
  percentage: number,
): Promise<boolean> {
  // Deterministic hash of userId
  const hash = hashCode(`${feature}:${userId}`);
  return (hash % 100) < percentage;
}
```

***

## Next Steps

* Process [Redis Streams](/docs/store/streams) for reliable message queues
* Set up [scopes and telemetry](/docs/store/advanced) for multi-tenancy
* Browse the complete [API reference](/docs/store/api-reference)


---

# Key-Value Operations

> Store and retrieve data with store.kv. Covers get, set, remove, exists, expire, and touch — with cache patterns, TTL management, and key naming conventions.
URL: https://igniterjs.com/docs/store/caching

## Overview

`store.kv` provides the fundamental key-value interface for `@igniter-js/store`. All values are automatically serialized to JSON by the adapter, so you can store any JSON-serializable data without manual conversion.

<Callout type="info">
  The key format is auto-prefixed by the store: `igniter:store:{service}[:scope...]:kv:{your-key}`. You only provide the logical key — scoping is handled transparently.
</Callout>

***

## Basic Operations

### `get<T>(key)` — Retrieve a value

```typescript
const user = await store.kv.get<{ name: string; email: string }>("user:123");

if (user) {
  console.log(user.name); // Fully typed
}
```

Returns `null` if the key doesn't exist.

### `set(key, value, options?)` — Store a value

```typescript
// Store indefinitely
await store.kv.set("user:123", { name: "Avery", email: "avery@example.com" });

// Store with TTL (time-to-live in seconds)
await store.kv.set("session:abc", sessionData, { ttl: 3600 }); // 1 hour
```

### `remove(key)` — Delete a key

```typescript
await store.kv.remove("user:123");

// Invalidate cache after update
await db.user.update({ where: { id: "123" }, data: newData });
await store.kv.remove("user:123");
```

### `exists(key)` — Check existence

```typescript
const exists = await store.kv.exists("user:123");

if (!exists) {
  const user = await fetchFromDatabase("123");
  await store.kv.set("user:123", user, { ttl: 3600 });
}
```

### `expire(key, ttlSeconds)` — Set/update TTL

```typescript
// Set TTL on existing key
await store.kv.set("config:app", config);
await store.kv.expire("config:app", 86400); // 24 hours

// Refresh TTL on access
const data = await store.kv.get("cache:key");
if (data) {
  await store.kv.expire("cache:key", 3600); // Extend
}
```

### `touch(key, ttlSeconds)` — Set TTL on existing key

```typescript
// `touch` is like `expire` but semantically signals "this key was accessed"
await store.kv.touch("user:123", 3600);
```

***

## Cache Patterns

### Cache-Aside (Read-Through)

The most common pattern: check cache first, fall back to source.

```typescript
async function getUser(id: string) {
  const cacheKey = `user:${id}`;

  // 1. Check cache
  const cached = await store.kv.get<User>(cacheKey);
  if (cached) return cached;

  // 2. Fetch from database
  const user = await db.user.findUnique({ where: { id } });
  if (!user) return null;

  // 3. Populate cache
  await store.kv.set(cacheKey, user, { ttl: 3600 });

  return user;
}
```

### Write-Through

Update cache and source simultaneously.

```typescript
async function updateUser(id: string, data: Partial<User>) {
  const user = await db.user.update({ where: { id }, data });
  await store.kv.set(`user:${id}`, user, { ttl: 3600 });
  return user;
}
```

### Cache Invalidation

```typescript
async function invalidateUserCache(userId: string) {
  await store.kv.remove(`user:${userId}`);
  await store.kv.remove(`user:${userId}:posts`);
  await store.kv.remove("users:list");
}
```

### Conditional Caching

```typescript
async function getExpensiveData(params: QueryParams) {
  const cacheKey = `data:${JSON.stringify(params)}`;
  const cached = await store.kv.get<Data>(cacheKey);
  if (cached) return cached;

  const data = await expensiveOperation(params);

  // Only cache successful responses
  if (data.status === "success") {
    await store.kv.set(cacheKey, data, { ttl: 300 });
  }

  return data;
}
```

***

## TTL Management

### Choosing TTL Values

| Data type      | Example            | Recommended TTL |
| -------------- | ------------------ | --------------- |
| Real-time data | Stock prices       | 15–60s          |
| User sessions  | Auth tokens        | 900–3600s       |
| API responses  | External API cache | 300–600s        |
| Configuration  | App settings       | 3600–86400s     |
| Static content | Page content       | 86400s+         |

### Refresh-on-Access

```typescript
async function getWithRefresh<T>(key: string, ttl: number): Promise<T | null> {
  const value = await store.kv.get<T>(key);
  if (value) {
    await store.kv.touch(key, ttl); // Extend lifetime
  }
  return value;
}
```

***

## Key Naming Conventions

Use colons (`:`) for hierarchical names:

```typescript
// Entity patterns
`user:${userId}`                    // Single entity
`users:list`                        // Collection
`users:list:page:${pageNumber}`    // Paginated

// Feature patterns
`session:${sessionId}`              // User session
`rate:limit:${userId}`              // Rate limiting
`api:response:${endpoint}`          // API cache

// Multi-tenant patterns
`tenant:${tenantId}:user:${userId}` // Tenant-scoped
`env:${env}:config:${key}`          // Environment-scoped
```

<Callout type="info" title="Best Practice">
  Use **scopes** (`addScope()` / `.scope()`) for tenant isolation instead of manual key prefixes. Scopes automatically handle key construction and prevent collisions.
</Callout>

***

## Error Handling

```typescript
async function safeGet<T>(key: string): Promise<T | null> {
  try {
    return await store.kv.get<T>(key);
  } catch (error) {
    if (error instanceof IgniterStoreError) {
      console.error(`Store error [${error.code}]:`, error.message);
    }
    return null; // Graceful degradation
  }
}
```

***

## Real-World Examples

### API Response Caching

```typescript
async function fetchWithCache(endpoint: string, params: Record<string, string>) {
  const cacheKey = `api:${endpoint}:${JSON.stringify(params)}`;

  const cached = await store.kv.get<ApiResponse>(cacheKey);
  if (cached) return { ...cached, source: "cache" };

  const data = await fetchFromApi(endpoint, params);
  await store.kv.set(cacheKey, data, { ttl: 600 });

  return { ...data, source: "api" };
}
```

### Session Management

```typescript
async function createSession(userId: string): Promise<string> {
  const sessionId = crypto.randomUUID();
  await store.kv.set(
    `session:${sessionId}`,
    { userId, createdAt: new Date().toISOString() },
    { ttl: 86400 } // 24 hours
  );
  return sessionId;
}

async function getSession(sessionId: string) {
  const session = await store.kv.get<SessionData>(`session:${sessionId}`);
  if (session) {
    await store.kv.touch(`session:${sessionId}`, 86400); // Refresh
  }
  return session;
}

async function deleteSession(sessionId: string) {
  await store.kv.remove(`session:${sessionId}`);
}
```

### Feature Flags

```typescript
async function isFeatureEnabled(feature: string, userId?: string): Promise<boolean> {
  // Check global flag
  const globalFlag = await store.kv.get<boolean>(`flag:global:${feature}`);
  if (globalFlag !== null) return globalFlag;

  // Check user-specific override
  if (userId) {
    const userFlag = await store.kv.get<boolean>(`flag:user:${userId}:${feature}`);
    if (userFlag !== null) return userFlag;
  }

  return false; // Default off
}
```

***

## Performance Tips

### Prefer Parallel Gets

```typescript
// ✅ Good — parallel
const [user1, user2, user3] = await Promise.all([
  store.kv.get("user:1"),
  store.kv.get("user:2"),
  store.kv.get("user:3"),
]);

// ❌ Bad — sequential (slower)
const user1 = await store.kv.get("user:1");
const user2 = await store.kv.get("user:2");
const user3 = await store.kv.get("user:3");
```

### Use `exists` instead of `get` for presence checks

```typescript
// ✅ Good — no value deserialization
if (await store.kv.exists("key")) { /* ... */ }

// ❌ Bad — deserializes value unnecessarily
const val = await store.kv.get("key");
if (val !== null) { /* ... */ }
```

***

## Next Steps

* Build [typed events and Pub/Sub](/docs/store/pubsub) for real-time communication
* Use [counters and claims](/docs/store/atomic-operations) for atomic operations
* Set up [multi-tenant scopes](/docs/store/advanced) for tenant isolation


---

# Installation

> Install @igniter-js/store with Redis or in-memory adapter. Set up your store instance with the builder pattern in under 2 minutes.
URL: https://igniterjs.com/docs/store/installation

## Prerequisites

* **Node.js** 22+ or **Bun** runtime
* **Redis** server (local or remote) — for production use
* **TypeScript** 5.6+ (recommended for full type inference)

<Callout type="info">
  Don't have Redis? Use the built-in memory adapter for development, testing, or desktop apps (Electron, Tauri, Bun).
</Callout>

***

## Installation

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/store ioredis zod
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/store ioredis zod
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/store ioredis zod
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/store ioredis zod
    ```
  </Tab>
</Tabs>

| Dependency          | Why                                              |
| ------------------- | ------------------------------------------------ |
| `@igniter-js/store` | The store library itself                         |
| `ioredis`           | Redis client (peer dependency for Redis adapter) |
| `zod`               | Schema validation for typed events               |

***

## Redis Setup

### Local Development

Run Redis with Docker:

```bash
docker run -d -p 6379:6379 redis:7-alpine
```

Or install natively:

**macOS:**

```bash
brew install redis && brew services start redis
```

**Linux (Ubuntu/Debian):**

```bash
sudo apt-get install redis-server && sudo systemctl start redis
```

Verify it's running:

```bash
redis-cli ping
# PONG
```

### Production

Use a managed Redis service:

* **Redis Cloud** (redis.com/cloud)
* **AWS ElastiCache**
* **Google Cloud Memorystore**
* **Azure Cache for Redis**

***

## Create Your Store (60 seconds)

```typescript
// src/store.ts
import Redis from "ioredis";
import { IgniterStore } from "@igniter-js/store";
import { IgniterStoreRedisAdapter } from "@igniter-js/store/adapters";

const redis = new Redis(process.env.REDIS_URL);

export const store = IgniterStore.create()
  .withAdapter(IgniterStoreRedisAdapter.create({ redis }))
  .withService("api")  // Used in key prefixes for isolation
  .build();
```

**That's it.** Your store is ready.

```typescript
// Use it anywhere
await store.kv.set("user:123", { name: "Avery" }, { ttl: 3600 });
const user = await store.kv.get("user:123");
console.log(user?.name); // "Avery"
```

***

## Redis Connection Options

```typescript
import Redis from "ioredis";

const redis = new Redis({
  host: process.env.REDIS_HOST || "localhost",
  port: Number(process.env.REDIS_PORT) || 6379,
  password: process.env.REDIS_PASSWORD,
  db: Number(process.env.REDIS_DB) || 0,

  // Retry strategy
  retryStrategy: (times) => {
    const delay = Math.min(times * 50, 2000);
    return delay;
  },
  maxRetriesPerRequest: 3,

  // Resilience
  enableOfflineQueue: true,
  lazyConnect: false,
});

// Connection events
redis.on("connect", () => console.log("Redis connected"));
redis.on("error", (err) => console.error("Redis error:", err));
```

### Redis Cluster

```typescript
import { Cluster } from "ioredis";

const cluster = new Cluster(
  [
    { host: "127.0.0.1", port: 7000 },
    { host: "127.0.0.1", port: 7001 },
    { host: "127.0.0.1", port: 7002 },
  ],
  {
    redisOptions: { password: process.env.REDIS_PASSWORD },
  }
);

const adapter = IgniterStoreRedisAdapter.create({ redis: cluster });
```

### Using a Redis URL

```typescript
const redis = new Redis(process.env.REDIS_URL);
// redis://user:pass@localhost:6379/0
```

***

## Memory Adapter (No Redis Required)

For development, testing, or environments where Redis isn't available:

```typescript
import { IgniterStore } from "@igniter-js/store";
import { IgniterStoreMemoryAdapter } from "@igniter-js/store/adapters";

const store = IgniterStore.create()
  .withAdapter(IgniterStoreMemoryAdapter.create())
  .withService("dev")
  .build();

// Same API — now backed by in-memory storage
await store.kv.set("key", "value");
const val = await store.kv.get("key");
```

<Callout type="success" title="Seamless swap">
  The memory adapter implements the full `IgniterStoreAdapter` contract — KV, counters, claims, batch, pub/sub, streams, and scan. Swap adapters without changing any business logic.
</Callout>

***

## Sharing a Redis Connection

Share the same Redis client across multiple adapters or packages:

```typescript
import Redis from "ioredis";
import { IgniterStoreRedisAdapter } from "@igniter-js/store/adapters";

// Single Redis client
export const redis = new Redis(process.env.REDIS_URL);

// Store adapter
export const storeAdapter = IgniterStoreRedisAdapter.create({ redis });

// The store internally duplicates the client for subscriptions
```

<Callout type="info">
  The Redis adapter creates an internal duplicate client for Pub/Sub subscriptions (Redis requirement). Your main `redis` client remains dedicated to commands.
</Callout>

***

## Environment Variables

```bash
# .env
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# Or
REDIS_URL=redis://localhost:6379/0
```

***

## Health Check

Verify connectivity at startup:

```typescript
async function checkStoreHealth(store: IgniterStoreManager) {
  try {
    await store.kv.set("health:check", "ok", { ttl: 10 });
    const result = await store.kv.get("health:check");
    return result === "ok";
  } catch {
    return false;
  }
}
```

***

## Next Steps

* [Key-value operations](/docs/store/caching) — caching patterns, TTL management
* [Events & Pub/Sub](/docs/store/pubsub) — typed, schema-driven Pub/Sub
* [Counters, claims & batch](/docs/store/atomic-operations) — atomic operations
* [Scopes & telemetry](/docs/store/advanced) — multi-tenancy and observability


---

# Store

> Type-safe distributed state, events, and streams for modern TypeScript apps. Redis-backed storage with scoped keys, typed Pub/Sub, and stream processing.
URL: https://igniterjs.com/docs/store/page

## Overview

`@igniter-js/store` is a **standalone, builder-based** distributed store library for TypeScript applications. It provides a unified, type-safe interface for key-value storage, counters, distributed locks (claims), batch operations, typed Pub/Sub events, and Redis Streams — all backed by a pluggable adapter architecture.

<Callout type="info">
  Store is **not a caching layer glued onto Igniter Core**. It's a fully independent package you can use in any Node.js or Bun application — whether you're building an Express API, a Next.js app, a Fastify service, or a background worker.
</Callout>

### Key Features

* **Namespaced API** — Clean separation: `store.kv`, `store.counter`, `store.claim`, `store.batch`, `store.events`, `store.streams`, `store.dev`
* **Typed Events** — Schema-driven Pub/Sub with Zod schemas, dual API (string + proxy), and wildcard subscriptions
* **Multi-Tenant Scopes** — Isolate data per organization, workspace, or environment with chained scope prefixes
* **Redis Streams** — Append, range queries, consumer groups with acknowledgment
* **Distributed Claims** — SETNX-based locks for leader election, cron deduplication
* **Two Adapters** — Production Redis adapter + in-memory adapter for testing/desktop
* **Observability** — Built-in telemetry events for every operation (`igniter.store.kv.*`, `igniter.store.stream.*`, etc.)

***

## Quick Start

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/store ioredis zod
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/store ioredis zod
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/store ioredis zod
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/store ioredis zod
    ```
  </Tab>
</Tabs>

```typescript
import Redis from "ioredis";
import { IgniterStore } from "@igniter-js/store";
import { IgniterStoreRedisAdapter } from "@igniter-js/store/adapters";

const redis = new Redis(process.env.REDIS_URL);

const store = IgniterStore.create()
  .withAdapter(IgniterStoreRedisAdapter.create({ redis }))
  .withService("api")
  .build();

// ✅ Key-value
await store.kv.set("user:123", { name: "Avery" }, { ttl: 3600 });
const user = await store.kv.get("user:123");

// ✅ Counter
const views = await store.counter.increment("page-views");

// ✅ Distributed claim
const claimed = await store.claim.once("job:cleanup", "worker-1", { ttl: 30 });

// ✅ Batch
const users = await store.batch.get(["user:1", "user:2", "user:3"]);
```

***

## Architecture

```
┌──────────────────────────────────────────────────────────────┐
│                      Your Application                         │
│  store.kv.set() • store.events.publish() • store.streams...   │
└───────────────┬──────────────────────────────────────────────┘
                │ Typed API + Scopes
                ▼
┌──────────────────────────────────────────────────────────────┐
│                 IgniterStoreManager                           │
│  KV • Counter • Claim • Batch • Events • Streams • Dev        │
└───────────────┬──────────────────────────────────────────────┘
                │ Adapter Contract
                ▼
┌──────────────────────────────────────────────────────────────┐
│              IgniterStoreAdapter (Redis / Memory)             │
└───────────────┬──────────────────────────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────────────────────────┐
│                         Redis / Memory                        │
└──────────────────────────────────────────────────────────────┘
```

### Key Abstractions

| Component                             | Role                                           |
| ------------------------------------- | ---------------------------------------------- |
| **Builder** (`IgniterStore.create()`) | Immutable, fluent configuration chain          |
| **Manager** (`IgniterStoreManager`)   | Runtime API with namespaced operations         |
| **Adapter** (`IgniterStoreAdapter`)   | Storage backend contract (Redis, Memory)       |
| **Events** (`IgniterStoreEvents`)     | Declarative typed event definitions with Zod   |
| **Scopes**                            | Multi-tenant isolation via key prefix chaining |
| **Telemetry**                         | Optional event emission for every operation    |

***

## Package Exports

| Path                          | Description                                                     |
| ----------------------------- | --------------------------------------------------------------- |
| `@igniter-js/store`           | Main API — `IgniterStore`, `IgniterStoreEvents`, types, errors  |
| `@igniter-js/store/adapters`  | Redis adapter (`IgniterStoreRedisAdapter`)                      |
| `@igniter-js/store/telemetry` | Typed telemetry events registry (`IgniterStoreTelemetryEvents`) |

***

## Next Steps

* [Install and configure](/docs/store/installation) the package with Redis
* Master [key-value operations](/docs/store/caching) with cache patterns
* Build [typed events and Pub/Sub](/docs/store/pubsub) with schema validation
* Use [counters, claims, and batch operations](/docs/store/atomic-operations)
* Process [Redis Streams](/docs/store/streams) with consumer groups
* Explore [scopes, telemetry, and custom adapters](/docs/store/advanced)
* Browse the complete [API reference](/docs/store/api-reference)


---

# Events & Pub/Sub

> Typed, schema-driven Pub/Sub with IgniterStoreEvents. Define event schemas with Zod, publish and subscribe with full type inference, and use wildcard patterns.
URL: https://igniterjs.com/docs/store/pubsub

## Overview

`@igniter-js/store` provides a fully typed Pub/Sub system with two complementary APIs:

1. **String-based API** — `store.events.publish("user:created", payload)`, `store.events.subscribe("user:created", handler)`
2. **Proxy-based API** — `store.events.user.created.publish(payload)`, `store.events.user.created.subscribe(handler)`

Both are powered by the same typed event registry, giving you full TypeScript inference for payloads and event names.

<Callout type="info">
  Events are scoped to your store instance. If you use scoped stores (`store.scope(...)`), published events and subscriptions are also scoped — each tenant gets isolated channels.
</Callout>

***

## Defining Typed Events

Use `IgniterStoreEvents` to define event schemas per feature module. Each feature exports its own events definition, which you combine in the store builder.

```typescript
import { z } from "zod";
import { IgniterStoreEvents } from "@igniter-js/store";

// src/features/user/user.events.ts
export const UserEvents = IgniterStoreEvents
  .create("user")
  .event("created", z.object({
    userId: z.string(),
    email: z.string().email(),
    createdAt: z.string(),
  }))
  .event("deleted", z.object({
    userId: z.string(),
    deletedAt: z.string(),
  }))
  .build();
```

### Nested Groups

Organize related events under groups:

```typescript
export const OrderEvents = IgniterStoreEvents
  .create("order")
  .event("placed", z.object({
    orderId: z.string(),
    total: z.number(),
  }))
  .group("fulfillment", (group) =>
    group
      .event("shipped", z.object({
        orderId: z.string(),
        trackingId: z.string(),
      }))
      .event("delivered", z.object({
        orderId: z.string(),
        deliveredAt: z.string(),
      }))
  )
  .group("payments", (group) =>
    group
      .event("authorized", z.object({
        orderId: z.string(),
        amount: z.number(),
      }))
      .event("refunded", z.object({
        orderId: z.string(),
        refundId: z.string(),
      }))
  )
  .build();
```

### Registering Events with the Store

```typescript
import { IgniterStore } from "@igniter-js/store";
import { UserEvents } from "./features/user/user.events";
import { OrderEvents } from "./features/order/order.events";

const store = IgniterStore.create()
  .withAdapter(adapter)
  .withService("api")
  .addEvents(UserEvents)
  .addEvents(OrderEvents)
  .build();
```

<Callout type="warn">
  Each namespace must be **unique** — calling `addEvents()` with the same namespace twice throws `STORE_DUPLICATE_NAMESPACE`.
</Callout>

***

## String-Based API

The string-based API uses colon-separated event names (`namespace:eventName`).

### Publishing

```typescript
// Fully typed — TypeScript knows the payload shape
await store.events.publish("user:created", {
  userId: "123",
  email: "avery@example.com",
  createdAt: new Date().toISOString(),
});

// Nested group event
await store.events.publish("order:fulfillment:shipped", {
  orderId: "o_456",
  trackingId: "TRK-789",
});
```

### Subscribing

The handler receives an `IgniterStoreEventContext` with `type`, `data`, `timestamp`, and optional `scope`:

```typescript
const unsubscribe = await store.events.subscribe("user:created", (ctx) => {
  console.log(ctx.type);      // "user:created"
  console.log(ctx.data);      // { userId: "123", email: "avery@example.com", ... }
  console.log(ctx.timestamp); // "2026-06-02T..."
  console.log(ctx.scope);     // undefined (or { key: "organization", identifier: "org_1" } if scoped)
});

// Later: stop listening
await unsubscribe();
```

### Wildcard Subscriptions

Subscribe to all events in a namespace using `*`:

```typescript
// Listen to all user events
await store.events.subscribe("user:*", (ctx) => {
  // ctx.type is "user:created" | "user:deleted"
  // ctx.data is the union of all user event payloads
  switch (ctx.type) {
    case "user:created":
      console.log("New user:", ctx.data.email);
      break;
    case "user:deleted":
      console.log("User deleted:", ctx.data.userId);
      break;
  }
});

// Listen to everything
await store.events.subscribe("*", (ctx) => {
  console.log(`[${ctx.type}]`, ctx.data);
});
```

***

## Proxy-Based API

The proxy API provides auto-completing access to typed events:

```typescript
// Publishing — fully typed, no string literals
await store.events.user.created.publish({
  userId: "123",
  email: "avery@example.com",
  createdAt: new Date().toISOString(),
});

// Nested groups
await store.events.order.fulfillment.shipped.publish({
  orderId: "o_456",
  trackingId: "TRK-789",
});

// Subscribing
const unsub = await store.events.user.created.subscribe((ctx) => {
  console.log(ctx.data.email); // Fully typed — no casting needed
});

await unsub();
```

<Callout type="success" title="Best Practice">
  Use the **proxy API** for individual event subscriptions (best DX with auto-complete), and the **string API** for wildcard subscriptions or dynamic event names.
</Callout>

***

## Event Context Envelope

Every handler receives an `IgniterStoreEventContext`:

| Field       | Type       | Description                                |
| ----------- | ---------- | ------------------------------------------ |
| `type`      | `string`   | Full event name (e.g., `"user:created"`)   |
| `data`      | `TPayload` | The event payload (typed from schema)      |
| `timestamp` | `string`   | ISO 8601 timestamp when published          |
| `scope`     | `object?`  | Current scope info if scoped store is used |

***

## Schema Validation

### Configuring Validation

Validation is configured per `addEvents()` call:

```typescript
const store = IgniterStore.create()
  .withAdapter(adapter)
  .withService("api")
  .addEvents(UserEvents, {
    validatePublish: true,     // Validate payloads when publishing (default: true)
    validateSubscribe: false,  // Validate received payloads (default: false)
    throwOnValidationError: true, // Throw on invalid payloads (default: true)
  })
  .build();
```

### Validation Behavior

```typescript
// ✅ Valid payload — succeeds
await store.events.publish("user:created", {
  userId: "123",
  email: "avery@example.com",
  createdAt: new Date().toISOString(),
});

// ❌ Invalid payload — throws STORE_SCHEMA_VALIDATION_FAILED
await store.events.publish("user:created", {
  userId: 123,        // Should be string
  email: "invalid",   // Not an email format
});
```

***

## Real-World Patterns

### Cross-Service Communication

```typescript
// Service A: Order placed
await store.events.publish("order:placed", {
  orderId: "o_123",
  userId: "u_456",
  total: 99.99,
  items: [{ productId: "p_1", quantity: 2 }],
});

// Service B: Send confirmation
await store.events.subscribe("order:placed", async (ctx) => {
  await emailService.sendConfirmation(ctx.data.userId, ctx.data.orderId);
});

// Service C: Update inventory
await store.events.subscribe("order:placed", async (ctx) => {
  for (const item of ctx.data.items) {
    await inventoryService.decrement(item.productId, item.quantity);
  }
});
```

### Cache Invalidation via Events

```typescript
// After database write, emit invalidation event
await db.user.update({ where: { id: userId }, data });
await store.events.publish("cache:invalidate:user", { userId });

// Cache layer listens and purges
await store.events.subscribe("cache:invalidate:user", async (ctx) => {
  await store.kv.remove(`user:${ctx.data.userId}`);
  await store.kv.remove("users:list");
});
```

### Activity Feed

```typescript
const ActivityEvents = IgniterStoreEvents
  .create("activity")
  .event("user_action", z.object({
    userId: z.string(),
    action: z.string(),
    metadata: z.record(z.unknown()).optional(),
  }))
  .build();

// Publish user actions
await store.events.activity.user_action.publish({
  userId: "u_123",
  action: "page_viewed",
  metadata: { page: "/dashboard", referrer: "/home" },
});

// Activity feed listener
await store.events.activity.user_action.subscribe(async (ctx) => {
  await db.activity.create({
    data: {
      userId: ctx.data.userId,
      action: ctx.data.action,
      metadata: ctx.data.metadata,
      createdAt: new Date(ctx.timestamp),
    },
  });
});
```

***

## Best Practices

### ✅ Organize Events by Feature

```typescript
// ✅ Good — one events file per feature
// features/user/user.events.ts
export const UserEvents = IgniterStoreEvents.create("user")...build();

// features/order/order.events.ts
export const OrderEvents = IgniterStoreEvents.create("order")...build();

// features/payment/payment.events.ts
export const PaymentEvents = IgniterStoreEvents.create("payment")...build();

// src/store.ts — combine them all
const store = IgniterStore.create()
  .addEvents(UserEvents)
  .addEvents(OrderEvents)
  .addEvents(PaymentEvents)
  .build();
```

### ❌ Don't Define Everything in One Place

```typescript
// ❌ Bad — monolithic, hard to maintain
const AllEvents = IgniterStoreEvents
  .create("all")
  .event("user:created", userSchema)
  .event("order:placed", orderSchema)
  .event("payment:authorized", paymentSchema)
  .build();
```

### ✅ Handle Errors in Subscribers

```typescript
await store.events.subscribe("order:placed", async (ctx) => {
  try {
    await processOrder(ctx.data);
  } catch (error) {
    console.error(`Failed to process order ${ctx.data.orderId}:`, error);
    // Don't let one failure break the subscription
  }
});
```

***

## Limitations

* **Wildcards in Redis**: The built-in Redis adapter uses `SUBSCRIBE` (exact channels), not `PSUBSCRIBE` (patterns). Wildcard matching is handled in TypeScript types only — for true Redis pattern subscriptions, implement a custom adapter. Use explicit channel names in production.
* **No at-least-once delivery**: Pub/Sub is fire-and-forget. For guaranteed delivery, use [Redis Streams](/docs/store/streams) with consumer groups.

***

## Next Steps

* Use [counters, claims, and batch operations](/docs/store/atomic-operations)
* Process [Redis Streams](/docs/store/streams) for reliable message processing
* Explore [scopes and telemetry](/docs/store/advanced)


---

# Redis Streams

> Append, read, and process Redis Streams with consumer groups. Build reliable message queues, event sourcing, and log processing with store.streams.
URL: https://igniterjs.com/docs/store/streams

## Overview

`store.streams` provides a typed interface for Redis Streams — an append-only log data structure perfect for reliable message processing, event sourcing, and log aggregation. Unlike Pub/Sub (fire-and-forget), streams support consumer groups, message acknowledgment, and message replay.

<Callout type="info">
  Streams are ideal when you need **at-least-once delivery**, message persistence, or the ability to replay events. For simple real-time notifications, use [Pub/Sub](/docs/store/pubsub) instead.
</Callout>

***

## Appending Messages

### Basic Append

```typescript
const messageId = await store.streams.append("events", {
  type: "user_signup",
  userId: "u_123",
  email: "avery@example.com",
  timestamp: new Date().toISOString(),
});

console.log(messageId); // "1685654738123-0"
```

### Append with Stream Capping

Limit stream length to prevent unbounded growth:

```typescript
await store.streams.append("events", payload, {
  maxLen: 10000,       // Keep at most 10,000 messages
  approximate: true,   // Use ~ for better performance
});

// Without approximate — exact trimming (slower)
await store.streams.append("events", payload, { maxLen: 10000 });
```

***

## Reading Messages

### Range Queries

Read a slice of the stream:

```typescript
// All messages
const all = await store.streams.range("events", {
  startId: "0",   // From beginning
  endId: "+",     // To end
});

// Last 100 messages
const recent = await store.streams.range("events", {
  startId: "-",
  endId: "+",
  count: 100,
});

// Messages after a specific ID
const after = await store.streams.range("events", {
  startId: "1685654738123-0",
  endId: "+",
});

// Each message: { id: "1685654738123-0", message: { type: "user_signup", ... } }
for (const msg of recent) {
  console.log(`${msg.id}:`, msg.message);
}
```

***

## Consumer Groups

Consumer groups enable multiple consumers to distribute message processing — each message is delivered to exactly one consumer in the group.

### Setup

```typescript
// Create a consumer in a group
const consumer = store.streams.group("processors", "worker-1");

// Ensure the consumer group exists (idempotent)
await consumer.ensure("events", { startId: "0" }); // Start from beginning
// Or: await consumer.ensure("events", { startId: "$" }); // Start from latest
```

### Reading as a Consumer

```typescript
// Read new messages (blocking)
const messages = await consumer.read("events", {
  count: 10,       // Max 10 messages
  blockMs: 5000,   // Block up to 5 seconds for new messages
});

for (const msg of messages) {
  console.log(msg.id, msg.message);

  // Process the message...
  await processMessage(msg.message);
}
```

### Acknowledging Messages

After processing, acknowledge messages to remove them from the pending list:

```typescript
const messages = await consumer.read("events", { count: 10 });

for (const msg of messages) {
  try {
    await processMessage(msg.message);
  } catch (error) {
    console.error(`Failed to process ${msg.id}:`, error);
    continue; // Don't ack — it will be retried
  }
}

// Acknowledge all successfully processed messages
await consumer.ack("events", messages.map((m) => m.id));
```

### Multiple Workers

Scale out by creating consumers on the same group:

```typescript
// Worker 1
const worker1 = store.streams.group("processors", "worker-1");
await worker1.ensure("events");

// Worker 2 (separate process)
const worker2 = store.streams.group("processors", "worker-2");
await worker2.ensure("events");

// Worker 3 (separate process)
const worker3 = store.streams.group("processors", "worker-3");
await worker3.ensure("events");

// Messages are distributed across workers — each message
// goes to exactly one worker in the "processors" group.
```

***

## Real-World Example: Order Processing Pipeline

```typescript
import { IgniterStore } from "@igniter-js/store";
import { IgniterStoreRedisAdapter } from "@igniter-js/store/adapters";
import Redis from "ioredis";

const store = IgniterStore.create()
  .withAdapter(IgniterStoreRedisAdapter.create({ redis: new Redis() }))
  .withService("orders")
  .build();

// --- Producer: Append to stream ---
async function submitOrder(order: Order) {
  const messageId = await store.streams.append("orders", order, {
    maxLen: 100000,
    approximate: true,
  });

  console.log(`Order ${order.id} submitted as ${messageId}`);
  return messageId;
}

// --- Consumer: Process orders ---
async function startOrderProcessor(workerId: string) {
  const consumer = store.streams.group("order-processors", workerId);
  await consumer.ensure("orders", { startId: "$" });

  console.log(`Worker ${workerId} started`);

  while (true) {
    const messages = await consumer.read("orders", {
      count: 5,
      blockMs: 5000,
    });

    if (messages.length === 0) continue;

    console.log(`Worker ${workerId}: Processing ${messages.length} orders`);

    const acked: string[] = [];

    for (const msg of messages) {
      try {
        await processOrder(msg.message);
        acked.push(msg.id);
      } catch (error) {
        console.error(`Worker ${workerId}: Failed ${msg.id}:`, error);
      }
    }

    if (acked.length > 0) {
      await consumer.ack("orders", acked);
    }
  }
}

// Start 3 workers (in separate processes or threads)
startOrderProcessor("worker-1");
startOrderProcessor("worker-2");
startOrderProcessor("worker-3");
```

***

## Chat Message Processing

```typescript
// Producer: Chat message
await store.streams.append("chat:room:general", {
  from: "alice",
  text: "Hello everyone!",
  timestamp: Date.now(),
}, { maxLen: 5000, approximate: true });

// Consumer: Chat archiver
const archiver = store.streams.group("archivers", "archiver-1");
await archiver.ensure("chat:room:general");

const messages = await archiver.read("chat:room:general", {
  count: 50,
  blockMs: 10000,
});

for (const msg of messages) {
  await db.message.create({ data: msg.message });
  await archiver.ack("chat:room:general", [msg.id]);
}
```

***

## Stream API Reference

### `store.streams.append(stream, message, options?)`

Append a message to a stream.

| Parameter             | Type       | Description                          |
| --------------------- | ---------- | ------------------------------------ |
| `stream`              | `string`   | Stream name                          |
| `message`             | `unknown`  | Message payload (serialized as JSON) |
| `options.maxLen`      | `number?`  | Maximum stream length                |
| `options.approximate` | `boolean?` | Use approximate trimming (\~)        |

Returns: `Promise<string>` — the message ID.

### `store.streams.group(group, consumer)`

Create a consumer in a group.

| Parameter  | Type     | Description                         |
| ---------- | -------- | ----------------------------------- |
| `group`    | `string` | Consumer group name                 |
| `consumer` | `string` | Consumer name (unique per instance) |

Returns: `IgniterStoreStreamConsumerGroup`

### Consumer Group Methods

**`consumer.ensure(stream, options?)`** — Create consumer group (idempotent).

| Parameter         | Type      | Description                                            |
| ----------------- | --------- | ------------------------------------------------------ |
| `stream`          | `string`  | Stream name                                            |
| `options.startId` | `string?` | `"0"` for beginning, `"$"` for latest (default: `"0"`) |

**`consumer.read(stream, options?)`** — Read pending messages.

| Parameter         | Type      | Description                            |
| ----------------- | --------- | -------------------------------------- |
| `stream`          | `string`  | Stream name                            |
| `options.count`   | `number?` | Max messages (default: 100)            |
| `options.blockMs` | `number?` | Block timeout in ms (0 = non-blocking) |

Returns: `Promise<Array<{ id: string; message: T }>>`

**`consumer.ack(stream, ids)`** — Acknowledge processed messages.

| Parameter | Type       | Description                |
| --------- | ---------- | -------------------------- |
| `stream`  | `string`   | Stream name                |
| `ids`     | `string[]` | Message IDs to acknowledge |

### `store.streams.range(stream, options?)`

Read a range of messages (non-consumer).

| Parameter         | Type       | Description               |
| ----------------- | ---------- | ------------------------- |
| `stream`          | `string`   | Stream name               |
| `options.startId` | `string?`  | Start ID (default: `"-"`) |
| `options.endId`   | `string?`  | End ID (default: `"+"`)   |
| `options.count`   | `number?`  | Max messages              |
| `options.reverse` | `boolean?` | Read in reverse order     |

***

## Next Steps

* Set up [multi-tenant scopes](/docs/store/advanced) for tenant-isolated streams
* Browse the [API reference](/docs/store/api-reference)
* See [troubleshooting](/docs/store/troubleshooting) for common stream issues


---

# Troubleshooting

> Common errors, connection issues, and debugging tips for @igniter-js/store. Solutions for Redis connectivity, schema validation, and performance problems.
URL: https://igniterjs.com/docs/store/troubleshooting

## Overview

This guide covers common issues you may encounter when using `@igniter-js/store` and how to resolve them.

***

## Connection Errors

### `ECONNREFUSED` — Redis not reachable

**Symptom:** Operations fail with `ECONNREFUSED`.

**Causes & Fixes:**

1. **Redis isn't running:**
   ```bash
   redis-cli ping
   # Should return: PONG
   ```
   If not, start Redis:
   ```bash
   docker run -d -p 6379:6379 redis:7-alpine
   # or: brew services start redis (macOS)
   ```

2. **Wrong host/port:**
   ```typescript
   // Check your configuration
   const redis = new Redis({
     host: "localhost",  // Not "127.0.0.1" if using Docker
     port: 6379,
   });
   ```

3. **Firewall blocking port 6379:**
   Check your firewall rules allow connections to Redis.

### `NOAUTH` — Authentication required

**Symptom:** `NOAUTH Authentication required.`

**Fix:** Provide the password:

```typescript
const redis = new Redis({
  host: "localhost",
  port: 6379,
  password: process.env.REDIS_PASSWORD,
});
```

***

## Schema Validation Errors

### `STORE_SCHEMA_VALIDATION_FAILED`

**Symptom:** Publishing or subscribing to events throws validation errors.

**Causes:**

1. **Payload doesn't match schema:**
   ```typescript
   // Schema expects { userId: string, email: string }
   const UserEvents = IgniterStoreEvents
     .create("user")
     .event("created", z.object({
       userId: z.string(),
       email: z.string().email(),
     }))
     .build();

   // ❌ Wrong — userId is number, email is malformed
   await store.events.publish("user:created", {
     userId: 123,
     email: "not-an-email",
   });

   // ✅ Correct
   await store.events.publish("user:created", {
     userId: "123",
     email: "avery@example.com",
   });
   ```

2. **To disable validation for debugging:**
   ```typescript
   .addEvents(UserEvents, {
     throwOnValidationError: false,
   })
   ```

### `STORE_DUPLICATE_NAMESPACE`

**Symptom:** `Namespace "user" is already registered.`

**Fix:** Each namespace can only be added once. Combine events from the same feature into a single `IgniterStoreEvents` definition:

```typescript
// ✅ Good — single definition per namespace
const UserEvents = IgniterStoreEvents
  .create("user")
  .event("created", createdSchema)
  .event("deleted", deletedSchema)
  .build();

// ❌ Bad — trying to add the same namespace twice
store.addEvents(UserEventsCreated);
store.addEvents(UserEventsDeleted); // Error: duplicate namespace
```

***

## Scope Errors

### `STORE_INVALID_SCOPE_KEY`

**Symptom:** `Scope key "workspace" is not defined.`

**Fix:** Define the scope with `addScope()` before using it:

```typescript
// This store only allows "organization" scope
const store = IgniterStore.create()
  .withAdapter(adapter)
  .withService("api")
  .addScope("organization")
  .build();

// ❌ "workspace" is not defined
store.scope("workspace", "ws_1");

// ✅ Use "organization" or add "workspace" to the builder
store.scope("organization", "org_1");
```

### `STORE_SCOPE_KEY_REQUIRED` / `STORE_SCOPE_IDENTIFIER_REQUIRED`

**Symptom:** `Scope key is required` or `Scope identifier is required`.

**Fix:** Always provide both key and identifier:

```typescript
// ❌ Missing identifier
store.scope("organization", "");

// ✅ Non-empty identifier
store.scope("organization", "org_123");
```

***

## Builder Errors

### `STORE_ADAPTER_REQUIRED`

**Symptom:** `Adapter is required.`

**Fix:** You must call `.withAdapter()` before `.build()`:

```typescript
// ❌ Missing adapter
const store = IgniterStore.create()
  .withService("api")
  .build();

// ✅ With adapter
const store = IgniterStore.create()
  .withAdapter(IgniterStoreRedisAdapter.create({ redis }))
  .withService("api")
  .build();
```

### `STORE_SERVICE_REQUIRED`

**Symptom:** `Service name is required.`

**Fix:** Always provide a service name:

```typescript
const store = IgniterStore.create()
  .withAdapter(adapter)
  .withService("my-service") // Required
  .build();
```

***

## Performance Issues

### Slow Operations

1. **Use batch operations for multiple keys:**
   ```typescript
   // ❌ Slow — N round trips
   for (const id of ids) {
     await store.kv.get(`user:${id}`);
   }

   // ✅ Fast — single round trip
   const users = await store.batch.get(ids.map(id => `user:${id}`));
   ```

2. **Use `exists` instead of `get` for presence checks:**
   ```typescript
   // ❌ Deserializes value unnecessarily
   const val = await store.kv.get("key");
   if (val !== null) { /* ... */ }

   // ✅ Only checks existence
   if (await store.kv.exists("key")) { /* ... */ }
   ```

3. **Set appropriate TTLs to prevent unbounded growth:**
   ```typescript
   // ✅ Always set TTL on cache entries
   await store.kv.set("key", value, { ttl: 3600 });

   // ❌ Never expires — memory leak
   await store.kv.set("key", value);
   ```

### Redis Memory Pressure

Monitor and configure Redis memory:

```bash
redis-cli CONFIG SET maxmemory 256mb
redis-cli CONFIG SET maxmemory-policy allkeys-lru
```

***

## Stream Issues

### `BUSYGROUP` — Consumer group already exists

This is **normal** and handled automatically. The adapter catches this and treats it as success. No action needed.

### Messages not being delivered

**Check:** Are you acknowledging messages? Unacknowledged messages stay in the pending list and won't be re-delivered until claimed.

```typescript
const messages = await consumer.read("events", { count: 10 });

// ✅ Always ack after processing
for (const msg of messages) {
  await processMessage(msg.message);
}
await consumer.ack("events", messages.map((m) => m.id));
```

### Stream grows unbounded

Always set `maxLen` when appending:

```typescript
await store.streams.append("events", payload, {
  maxLen: 10000,
  approximate: true,
});
```

***

## TypeScript Issues

### Type inference not working for events

Make sure you're using the builder correctly:

```typescript
// ✅ Events are typed because they're registered
const store = IgniterStore.create()
  .withAdapter(adapter)
  .withService("api")
  .addEvents(UserEvents) // Registers types
  .build();

// Now fully typed
store.events.user.created.publish({ userId: "...", email: "...", createdAt: "..." });

// ❌ Without addEvents(), no type inference
store.events.publish("user:created", {}); // any
```

***

## Best Practices Checklist

* [ ] Always set TTL on cache entries
* [ ] Use `store.batch` for multi-key operations
* [ ] Define scopes with `addScope()` for type safety
* [ ] Organize events by feature module
* [ ] Always acknowledge stream messages after processing
* [ ] Use the memory adapter for tests
* [ ] Configure telemetry redaction in production
* [ ] Handle errors gracefully — don't let one failure cascade

***

## Getting Help

* Browse the complete [API reference](/docs/store/api-reference)
* Check the [package README](https://github.com/igniter-js/igniter-js/blob/main/packages/store/README.md)
* See [advanced patterns](/docs/store/advanced) for production guidance


---

# Transport Adapters

> All 10 built-in transport adapters — Logger, HTTP, OTLP, Sentry, Slack, Discord, Telegram, Memory, Mock, and Store. Compare features, see configuration, and build custom adapters.
URL: https://igniterjs.com/docs/telemetry/adapters

## Transport Adapters

Transport adapters are **pluggable destinations** for telemetry events. Each adapter receives the event envelope and routes it to its target — a log file, a monitoring service, a chat platform, or your own backend.

***

## Adapter Comparison

| Adapter  | Use Case                  | Dependencies        | Import Path                      |
| -------- | ------------------------- | ------------------- | -------------------------------- |
| Logger   | Console/file logging      | None                | `@igniter-js/telemetry/adapters` |
| HTTP     | Webhook POST to any URL   | None                | `@igniter-js/telemetry/adapters` |
| OTLP     | OpenTelemetry collector   | None                | `@igniter-js/telemetry/adapters` |
| Sentry   | Error monitoring          | `@sentry/node`      | `@igniter-js/telemetry/adapters` |
| Slack    | Team notifications        | None                | `@igniter-js/telemetry/adapters` |
| Discord  | Team notifications        | None                | `@igniter-js/telemetry/adapters` |
| Telegram | Team notifications        | None                | `@igniter-js/telemetry/adapters` |
| Memory   | Testing/debugging         | None                | `@igniter-js/telemetry/adapters` |
| Mock     | Unit testing              | None                | `@igniter-js/telemetry/adapters` |
| Store    | Redis Streams persistence | `@igniter-js/store` | `@igniter-js/telemetry/adapters` |

***

## Logger Adapter

Outputs events to any logger with `info()`, `warn()`, `error()`, and `debug()` methods.

```typescript
import { LoggerTransportAdapter } from "@igniter-js/telemetry/adapters";

const logger = LoggerTransportAdapter.create({
  logger: console,
  format: "json",           // "json" | "pretty"
  minLevel: "info",         // Minimum level to log
  includeTimestamp: true,   // Include ISO timestamp
});
```

| Option             | Type                 | Default    | Description                                     |
| ------------------ | -------------------- | ---------- | ----------------------------------------------- |
| `logger`           | `object`             | required   | Any object with `info/warn/error/debug` methods |
| `format`           | `"json" \| "pretty"` | `"pretty"` | Output format                                   |
| `minLevel`         | `string`             | `"debug"`  | Minimum level to log                            |
| `includeTimestamp` | `boolean`            | `true`     | Include ISO 8601 timestamp                      |

```typescript
// JSON format output
const jsonLogger = LoggerTransportAdapter.create({
  logger: console,
  format: "json",
});

// Filter to errors only
const errorLogger = LoggerTransportAdapter.create({
  logger: console,
  format: "pretty",
  minLevel: "error",
});
```

***

## HTTP Adapter

Sends events as JSON via HTTP POST to any URL.

```typescript
import { HttpTransportAdapter } from "@igniter-js/telemetry/adapters";

const http = HttpTransportAdapter.create({
  url: "https://webhook.example.com/telemetry",
  headers: {
    Authorization: `Bearer ${process.env.TELEMETRY_TOKEN}`,
    "X-Service-Name": "billing-api",
  },
  timeout: 4000,    // Request timeout in ms
  retries: 2,       // Number of retries on failure
});
```

| Option    | Type                     | Default  | Description                  |
| --------- | ------------------------ | -------- | ---------------------------- |
| `url`     | `string`                 | required | Target webhook URL           |
| `headers` | `Record<string, string>` | `{}`     | Custom HTTP headers          |
| `timeout` | `number`                 | `5000`   | Request timeout in ms        |
| `retries` | `number`                 | `0`      | Number of retries on failure |

***

## OTLP Adapter

Sends events to an OpenTelemetry collector via OTLP HTTP.

```typescript
import { OtlpTransportAdapter } from "@igniter-js/telemetry/adapters";

const otlp = OtlpTransportAdapter.create({
  url: "http://localhost:4318/v1/logs",
  headers: {
    "x-api-key": process.env.OTEL_API_KEY ?? "",
  },
});
```

| Option    | Type                     | Default  | Description        |
| --------- | ------------------------ | -------- | ------------------ |
| `url`     | `string`                 | required | OTLP HTTP endpoint |
| `headers` | `Record<string, string>` | `{}`     | Custom headers     |

<Callout type="info">
  The OTLP adapter sends events as **OTLP Logs** over HTTP. Point it at any OTEL collector (Jaeger, Grafana Tempo, Datadog Agent with OTLP ingest).
</Callout>

***

## Sentry Adapter

Forwards error-level events to Sentry for error monitoring.

```typescript
import * as Sentry from "@sentry/node";
import { SentryTransportAdapter } from "@igniter-js/telemetry/adapters";

Sentry.init({ dsn: process.env.SENTRY_DSN });

const sentry = SentryTransportAdapter.create({
  sentry: Sentry,
});
```

| Option   | Type            | Default  | Description                     |
| -------- | --------------- | -------- | ------------------------------- |
| `sentry` | `typeof Sentry` | required | Initialized Sentry SDK instance |

<Callout type="info">
  The Sentry adapter only forwards **error-level** events. Info, debug, and warn events are ignored. Initialize Sentry with `Sentry.init()` before creating the adapter.
</Callout>

***

## Slack Adapter

Posts events to a Slack channel via webhook.

```typescript
import { SlackTransportAdapter } from "@igniter-js/telemetry/adapters";

const slack = SlackTransportAdapter.create({
  webhookUrl: process.env.SLACK_WEBHOOK_URL ?? "",
  minLevel: "error",                    // Only error+ events
  username: "Igniter Bot",
  iconEmoji: ":rotating_light:",
});
```

| Option       | Type     | Default               | Description                 |
| ------------ | -------- | --------------------- | --------------------------- |
| `webhookUrl` | `string` | required              | Slack incoming webhook URL  |
| `minLevel`   | `string` | `"warn"`              | Minimum event level to post |
| `username`   | `string` | `"Igniter Telemetry"` | Bot display name            |
| `iconEmoji`  | `string` | `":bar_chart:"`       | Bot icon emoji              |

***

## Discord Adapter

Posts events to a Discord channel via webhook.

```typescript
import { DiscordTransportAdapter } from "@igniter-js/telemetry/adapters";

const discord = DiscordTransportAdapter.create({
  webhookUrl: process.env.DISCORD_WEBHOOK_URL ?? "",
  minLevel: "warn",
  username: "Igniter Bot",
  avatarUrl: "https://example.com/bot-avatar.png",
});
```

| Option       | Type     | Default               | Description         |
| ------------ | -------- | --------------------- | ------------------- |
| `webhookUrl` | `string` | required              | Discord webhook URL |
| `minLevel`   | `string` | `"warn"`              | Minimum event level |
| `username`   | `string` | `"Igniter Telemetry"` | Bot display name    |
| `avatarUrl`  | `string` | —                     | Bot avatar URL      |

***

## Telegram Adapter

Sends events to a Telegram chat via bot API.

```typescript
import { TelegramTransportAdapter } from "@igniter-js/telemetry/adapters";

const telegram = TelegramTransportAdapter.create({
  botToken: process.env.TELEGRAM_BOT_TOKEN ?? "",
  chatId: process.env.TELEGRAM_CHAT_ID ?? "",
  minLevel: "error",
});
```

| Option     | Type     | Default   | Description                        |
| ---------- | -------- | --------- | ---------------------------------- |
| `botToken` | `string` | required  | Telegram bot token from @BotFather |
| `chatId`   | `string` | required  | Target chat ID                     |
| `minLevel` | `string` | `"error"` | Minimum event level                |

***

## In-Memory Adapter

Stores events in memory. Ideal for testing and debugging.

```typescript
import { InMemoryTransportAdapter } from "@igniter-js/telemetry/adapters";

const memory = InMemoryTransportAdapter.create();

const telemetry = IgniterTelemetry.create()
  .withService("test")
  .addTransport(memory)
  .build();

telemetry.emit("test.event.one", {
  attributes: { "ctx.value": 1 },
});
telemetry.emit("test.event.two", {
  attributes: { "ctx.value": 2 },
});

// Inspect captured events
const events = memory.getEvents();
console.log(events.length);       // 2
console.log(events[0].name);      // "test.event.one"
console.log(events[0].attributes); // { "ctx.value": 1 }

// Clear events
memory.clear();
```

| Method         | Description                 |
| -------------- | --------------------------- |
| `.getEvents()` | Returns all captured events |
| `.clear()`     | Clears all captured events  |

***

## Mock Adapter

Records events and provides assertion helpers. Designed for unit tests.

```typescript
import { MockTelemetryAdapter } from "@igniter-js/telemetry/adapters";

const mock = MockTelemetryAdapter.create();

const telemetry = IgniterTelemetry.create()
  .withService("test")
  .addTransport(mock)
  .build();

telemetry.emit("user.created", {
  attributes: { "ctx.user.id": "usr_001" },
});

// Assertions
expect(mock.getLastEvent()?.name).toBe("user.created");
expect(mock.getLastEvent()?.attributes).toEqual({
  "ctx.user.id": "usr_001",
});
```

| Method            | Description                   |
| ----------------- | ----------------------------- |
| `.getLastEvent()` | Returns the most recent event |
| `.getEvents()`    | Returns all captured events   |
| `.clear()`        | Clears captured events        |

***

## Store Stream Adapter

Persists events to Redis Streams via `@igniter-js/store`. Best for durable event storage and replay.

```typescript
import { IgniterStore } from "@igniter-js/store";
import { StoreStreamTransportAdapter } from "@igniter-js/telemetry/adapters";

const store = IgniterStore.create()
  .withAdapter(redisAdapter)
  .withNamespace("telemetry")
  .build();

const storeTransport = StoreStreamTransportAdapter.create({
  store,
  stream: "telemetry:events",
  maxLen: 10000,   // Max stream length (capped)
});
```

| Option   | Type           | Default              | Description                    |
| -------- | -------------- | -------------------- | ------------------------------ |
| `store`  | `IgniterStore` | required             | Initialized store instance     |
| `stream` | `string`       | `"telemetry:events"` | Redis Stream key               |
| `maxLen` | `number`       | `10000`              | Maximum stream length (capped) |

<Callout type="info">
  The Store adapter requires `@igniter-js/store` as a peer dependency. Install it separately: `npm install @igniter-js/store`.
</Callout>

***

## Multiple Transports

Add as many transports as you need — events fan out to all of them:

```typescript
const telemetry = IgniterTelemetry.create()
  .withService("api")
  .addTransport(LoggerTransportAdapter.create({ logger: console }))
  .addTransport(HttpTransportAdapter.create({ url: "https://..." }))
  .addTransport(SentryTransportAdapter.create({ sentry: Sentry }))
  .addTransport(SlackTransportAdapter.create({ webhookUrl: "..." }))
  .build();

// All four transports receive every event
telemetry.emit("payment.failed", {
  level: "error",
  error: { name: "PaymentError", message: "..." },
});
```

<Callout type="warn">
  If **all** transports fail for a given event, telemetry throws `TELEMETRY_TRANSPORT_FAILED`. Individual transport failures are silently logged but do not prevent other transports from receiving the event.
</Callout>

***

## Custom Transport Adapter

Implement the `IgniterTelemetryTransportAdapter` interface to create your own adapter:

```typescript
import type {
  IgniterTelemetryTransportAdapter,
  IgniterTelemetryEnvelope,
  IgniterTelemetryTransportMeta,
} from "@igniter-js/telemetry";

class DatadogTransport implements IgniterTelemetryTransportAdapter {
  readonly type = "datadog" as const;

  async init(meta: IgniterTelemetryTransportMeta): Promise<void> {
    // Optional: validate API key, open connection
    console.log(`Datadog transport initialized for ${meta.service}`);
  }

  async handle(envelope: IgniterTelemetryEnvelope): Promise<void> {
    await fetch("https://http-intake.logs.datadoghq.com/api/v2/logs", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "DD-API-KEY": process.env.DD_API_KEY!,
      },
      body: JSON.stringify({
        ddsource: envelope.service,
        ddtags: `env:${envelope.environment}`,
        service: envelope.service,
        message: envelope.name,
        ...envelope,
      }),
    });
  }

  async flush(): Promise<void> {
    // Optional: flush any buffered events
  }

  async shutdown(): Promise<void> {
    // Optional: close connections, cleanup
  }
}

// Use it
const telemetry = IgniterTelemetry.create()
  .withService("api")
  .addTransport(new DatadogTransport())
  .build();
```

### Adapter Interface

| Method             | Required | Description                                |
| ------------------ | -------- | ------------------------------------------ |
| `type`             | Yes      | Unique adapter identifier string           |
| `init(meta)`       | No       | Called during `.build()` — validate/set up |
| `handle(envelope)` | Yes      | Process a telemetry event                  |
| `flush()`          | No       | Flush buffered events                      |
| `shutdown()`       | No       | Graceful cleanup                           |

***

## Next Steps

* [Sampling & Redaction](/docs/telemetry/sampling-redaction) — Control volume and protect PII
* [Emitting Events](/docs/telemetry/emitting-events) — Attributes, levels, errors, and source metadata
* [API Reference](/docs/telemetry/api-reference) — Complete API documentation


---

# API Reference

> Complete API reference for @igniter-js/telemetry — IgniterTelemetry, IgniterTelemetryEvents, IgniterTelemetrySession, all transport adapters, types, and error codes.
URL: https://igniterjs.com/docs/telemetry/api-reference

## API Reference

Complete reference for all public APIs in `@igniter-js/telemetry`. Every method and type is verified against the implementation in `packages/telemetry/src/`.

***

## IgniterTelemetry (Builder)

**Import:** `import { IgniterTelemetry } from "@igniter-js/telemetry"`

Alias for `IgniterTelemetryBuilder`. Creates and configures telemetry instances.

### Static Methods

| Method                      | Returns                   | Description                   |
| --------------------------- | ------------------------- | ----------------------------- |
| `IgniterTelemetry.create()` | `IgniterTelemetryBuilder` | Create a new builder instance |

### Builder Methods

All builder methods are immutable — each returns a new builder instance.

| Method                    | Signature                                                       | Description                                 |
| ------------------------- | --------------------------------------------------------------- | ------------------------------------------- |
| `.withService(name)`      | `(service: string) => Builder`                                  | Set service name (default: `"igniter-app"`) |
| `.withEnvironment(env)`   | `(environment: string) => Builder`                              | Set environment (default: `"development"`)  |
| `.withVersion(v)`         | `(version: string) => Builder`                                  | Set service version                         |
| `.addActor(key, opts?)`   | `(key: string, opts?: ActorOptions) => Builder`                 | Register actor type                         |
| `.addScope(key, opts?)`   | `(key: string, opts?: ScopeOptions) => Builder`                 | Register scope type                         |
| `.addEvents(desc, opts?)` | `(desc: EventsDescriptor, opts?: ValidationOptions) => Builder` | Register typed events                       |
| `.addTransport(adapter)`  | `(adapter: TransportAdapter) => Builder`                        | Add transport adapter                       |
| `.withSampling(policy)`   | `(policy: SamplingPolicy) => Builder`                           | Configure sampling                          |
| `.withRedaction(policy)`  | `(policy: RedactionPolicy) => Builder`                          | Configure redaction                         |
| `.withValidation(opts)`   | `(opts: ValidationOptions) => Builder`                          | Set global validation options               |
| `.withLogger(logger)`     | `(logger: IgniterLogger) => Builder`                            | Set internal logger                         |
| `.build()`                | `IgniterTelemetryManager`                                       | Create runtime manager                      |
| `.buildConfig()`          | `IgniterTelemetryConfig`                                        | Build config only                           |

### ActorOptions

```typescript
interface IgniterTelemetryActorOptions {
  description?: string;
  required?: boolean;
}
```

### ScopeOptions

```typescript
interface IgniterTelemetryScopeOptions {
  description?: string;
  required?: boolean;
}
```

### ValidationOptions

```typescript
interface IgniterTelemetryEventsValidationOptions {
  mode?: "development" | "always" | "none";
  strict?: boolean;
}
```

***

## IgniterTelemetryManager (Runtime)

Returned by `.build()`. The runtime instance for emitting events.

### Properties

| Property      | Type                  | Description      |
| ------------- | --------------------- | ---------------- |
| `service`     | `string`              | Service name     |
| `environment` | `string`              | Environment name |
| `version`     | `string \| undefined` | Service version  |

### Methods

| Method                | Signature                                   | Description                 |
| --------------------- | ------------------------------------------- | --------------------------- |
| `.emit(name, input?)` | `(name: string, input?: EmitInput) => void` | Emit an event               |
| `.session()`          | `() => IgniterTelemetrySession`             | Create a new session        |
| `.flush()`            | `() => Promise<void>`                       | Flush all transport buffers |
| `.shutdown()`         | `() => Promise<void>`                       | Graceful shutdown           |

### EmitInput

```typescript
interface IgniterTelemetryEmitInput {
  level?: "debug" | "info" | "warn" | "error" | "fatal";
  time?: string;
  sessionId?: string;
  actor?: { type: string; id?: string; tags?: Record<string, unknown> };
  scope?: { type: string; id: string; tags?: Record<string, unknown> };
  attributes?: Record<string, unknown>;
  error?: {
    name: string;
    message: string;
    code?: string;
    stack?: string;
  };
  source?: {
    causer?: string;
    file?: string;
    line?: number;
  };
}
```

***

## IgniterTelemetrySession

Created via `telemetry.session()`. Provides context binding and scoped execution.

### Methods

| Method                     | Signature                                          | Description               |
| -------------------------- | -------------------------------------------------- | ------------------------- |
| `.actor(type, id?, tags?)` | `(type: string, id?: string, tags?: Tags) => this` | Set actor                 |
| `.scope(type, id, tags?)`  | `(type: string, id: string, tags?: Tags) => this`  | Set scope                 |
| `.attributes(attrs)`       | `(attrs: Record<string, unknown>) => this`         | Merge attributes          |
| `.id(sessionId)`           | `(sessionId: string) => this`                      | Set custom session ID     |
| `.emit(name, input?)`      | `(name: string, input?: EmitInput) => void`        | Emit with session context |
| `.run(fn)`                 | `(fn: () => Promise<T> \| T) => Promise<T>`        | Scoped execution          |
| `.end()`                   | `() => Promise<void>`                              | End session               |
| `.getState()`              | `() => SessionState`                               | Get session state copy    |

### Static Methods

| Method                                | Returns                     | Description                               |
| ------------------------------------- | --------------------------- | ----------------------------------------- |
| `IgniterTelemetrySession.getActive()` | `SessionState \| undefined` | Get active session from AsyncLocalStorage |

***

## IgniterTelemetryEvents

**Import:** `import { IgniterTelemetryEvents } from "@igniter-js/telemetry"`

Creates typed event registries with Zod schema validation.

### Methods

| Method                  | Signature                                                                            | Description          |
| ----------------------- | ------------------------------------------------------------------------------------ | -------------------- |
| `.namespace(name)`      | `(name: string) => EventRegistryBuilder`                                             | Start a namespace    |
| `.event(name, schema)`  | `(name: string, schema: Schema) => EventRegistryBuilder`                             | Add flat event       |
| `.group(name, builder)` | `(name: string, builder: (g: GroupBuilder) => GroupBuilder) => EventRegistryBuilder` | Add nested group     |
| `.build()`              | `EventsDescriptor`                                                                   | Build the descriptor |

### EventsDescriptor Helpers

| Helper              | Type                      | Description                       |
| ------------------- | ------------------------- | --------------------------------- |
| `.get.key(name)`    | `(key: string) => string` | Get full event key with namespace |
| `.get.schema(name)` | `(key: string) => Schema` | Get schema for event              |
| `.$Infer.namespace` | `string`                  | Namespace type                    |
| `.$Infer.events`    | `EventsMap`               | Events map type                   |
| `.$Infer.keys`      | `string union`            | All event key types               |
| `.$Infer.registry`  | `Registry`                | Full registry type                |

***

## Transport Adapters

**Import:** `import { ... } from "@igniter-js/telemetry/adapters"`

### LoggerTransportAdapter

```typescript
LoggerTransportAdapter.create(options: {
  logger: { info, warn, error, debug };  // Required
  format?: "json" | "pretty";            // Default: "pretty"
  minLevel?: string;                       // Default: "debug"
  includeTimestamp?: boolean;              // Default: true
})
```

### HttpTransportAdapter

```typescript
HttpTransportAdapter.create(options: {
  url: string;                             // Required
  headers?: Record<string, string>;        // Default: {}
  timeout?: number;                        // Default: 5000
  retries?: number;                        // Default: 0
})
```

### OtlpTransportAdapter

```typescript
OtltpTransportAdapter.create(options: {
  url: string;                             // Required
  headers?: Record<string, string>;        // Default: {}
})
```

### SentryTransportAdapter

```typescript
SentryTransportAdapter.create(options: {
  sentry: typeof Sentry;                   // Required
})
```

### SlackTransportAdapter

```typescript
SlackTransportAdapter.create(options: {
  webhookUrl: string;                      // Required
  minLevel?: string;                       // Default: "warn"
  username?: string;                       // Default: "Igniter Telemetry"
  iconEmoji?: string;                      // Default: ":bar_chart:"
})
```

### DiscordTransportAdapter

```typescript
DiscordTransportAdapter.create(options: {
  webhookUrl: string;                      // Required
  minLevel?: string;                       // Default: "warn"
  username?: string;                       // Default: "Igniter Telemetry"
  avatarUrl?: string;
})
```

### TelegramTransportAdapter

```typescript
TelegramTransportAdapter.create(options: {
  botToken: string;                        // Required
  chatId: string;                          // Required
  minLevel?: string;                       // Default: "error"
})
```

### InMemoryTransportAdapter

```typescript
InMemoryTransportAdapter.create()

// Methods:
.getEvents() => Envelope[]   // Get all captured events
.clear()                      // Clear captured events
```

### MockTelemetryAdapter

```typescript
MockTelemetryAdapter.create()

// Methods:
.getLastEvent() => Envelope | undefined  // Most recent event
.getEvents() => Envelope[]               // All captured events
.clear()                                  // Clear captured events
```

### StoreStreamTransportAdapter

```typescript
StoreStreamTransportAdapter.create(options: {
  store: IgniterStore;                     // Required
  stream?: string;                         // Default: "telemetry:events"
  maxLen?: number;                         // Default: 10000
})
```

***

## Transport Adapter Interface

```typescript
interface IgniterTelemetryTransportAdapter {
  readonly type: string;
  init?(meta: TransportMeta): Promise<void>;
  handle(envelope: Envelope): Promise<void>;
  flush?(): Promise<void>;
  shutdown?(): Promise<void>;
}

interface IgniterTelemetryTransportMeta {
  service: string;
  environment: string;
  version?: string;
}
```

***

## Sampling Policy

```typescript
interface IgniterTelemetrySamplingPolicy {
  debugRate?: number;       // Default: 0.01
  infoRate?: number;        // Default: 0.1
  warnRate?: number;        // Default: 1.0
  errorRate?: number;       // Default: 1.0
  always?: string[];        // Glob patterns always sampled
  never?: string[];         // Glob patterns never sampled
}
```

***

## Redaction Policy

```typescript
interface IgniterTelemetryRedactionPolicy {
  denylistKeys?: string[];    // Keys to remove (case-insensitive)
  hashKeys?: string[];        // Keys to SHA-256 hash (case-insensitive)
  maxStringLength?: number;   // Default: 5000
}
```

***

## Event Envelope

```typescript
interface IgniterTelemetryEnvelope {
  name: string;
  time: string;
  level: "debug" | "info" | "warn" | "error" | "fatal";
  service: string;
  environment: string;
  version?: string;
  sessionId: string;
  actor?: { type: string; id?: string; tags?: Record<string, unknown> };
  scope?: { type: string; id: string; tags?: Record<string, unknown> };
  attributes?: Record<string, unknown>;
  error?: { name: string; message: string; code?: string; stack?: string };
  source?: { causer?: string; file?: string; line?: number };
}
```

***

## Error Codes

```typescript
import { IgniterTelemetryError, IGNITER_TELEMETRY_ERROR_CODES } from "@igniter-js/telemetry";

// Configuration
TELEMETRY_SERVICE_REQUIRED
TELEMETRY_ENVIRONMENT_REQUIRED
TELEMETRY_CONFIGURATION_INVALID

// Transport
TELEMETRY_INVALID_TRANSPORT
TELEMETRY_TRANSPORT_FAILED
TELEMETRY_TRANSPORT_INIT_FAILED

// Events
TELEMETRY_INVALID_EVENT_NAME
TELEMETRY_UNKNOWN_EVENT
TELEMETRY_DUPLICATE_EVENT

// Schema & Validation
TELEMETRY_SCHEMA_VALIDATION_FAILED
TELEMETRY_INVALID_NAMESPACE
TELEMETRY_RESERVED_NAMESPACE
TELEMETRY_DUPLICATE_NAMESPACE

// Sessions
TELEMETRY_SESSION_ENDED
TELEMETRY_SESSION_INVALID

// Scope & Actor
TELEMETRY_DUPLICATE_SCOPE
TELEMETRY_INVALID_SCOPE
TELEMETRY_DUPLICATE_ACTOR
TELEMETRY_INVALID_ACTOR

// Emit & Runtime
TELEMETRY_EMIT_FAILED
TELEMETRY_RUNTIME_NOT_INITIALIZED
```

### Error Class

```typescript
class IgniterTelemetryError extends IgniterError {
  readonly code: IgniterTelemetryErrorCode;
  static is(error: unknown): error is IgniterTelemetryError;
  hasCode(code: IgniterTelemetryErrorCode): boolean;
}
```

***

## Event Levels

```typescript
type IgniterTelemetryLevel = "debug" | "info" | "warn" | "error" | "fatal";

// Level priority values (used internally for minLevel filtering)
IGNITER_TELEMETRY_LEVEL_PRIORITY = { debug: 10, info: 20, warn: 30, error: 40, fatal: 50 }
```

***

## Utility Types

```typescript
// Event registry types
type IgniterTelemetryFlattenRegistryKeys<TRegistry>;
type IgniterTelemetryGetEventSchema<TRegistry, TKey>;
type IgniterTelemetryInferEventSchema<TSchema>;

// Session types
type IgniterTelemetrySessionState;
type IIgniterTelemetrySession<TActor, TScope>;

// Manager type
type IIgniterTelemetryManager<TRegistry, TScopes, TActors>;
```

***

## Next Steps

* [Getting Started](/docs/telemetry/getting-started) — Complete walkthrough
* [Best Practices](/docs/telemetry/best-practices) — Production patterns
* [Troubleshooting](/docs/telemetry/troubleshooting) — Common errors and solutions


---

# Best Practices

> Production-tested patterns and anti-patterns for @igniter-js/telemetry — session management, event design, transport configuration, error handling, and performance optimization.
URL: https://igniterjs.com/docs/telemetry/best-practices

## Best Practices

This guide covers patterns that make telemetry reliable, performant, and maintainable in production. Every recommendation is grounded in the actual implementation.

***

## Session Management

### ✅ Do: Use scoped execution for HTTP handlers

```typescript
// ✅ Session context auto-propagates across all async calls
app.get("/api/orders/:id", async (req, res) => {
  await telemetry.session()
    .actor("user", req.userId)
    .scope("organization", req.orgId)
    .run(async () => {
      telemetry.emit("request.started");

      const order = await fetchOrder(req.params.id);
      telemetry.emit("order.fetched", {
        attributes: { "ctx.order.id": order.id },
      });

      res.json(order);

      telemetry.emit("request.completed", {
        attributes: { "ctx.request.status": 200 },
      });
    });
});
```

### ❌ Don't: Pass context manually to every emit

```typescript
// ❌ Repetitive, error-prone, easy to miss a call
telemetry.emit("request.started", {
  actor: { type: "user", id: req.userId },
  scope: { type: "organization", id: req.orgId },
});
telemetry.emit("order.fetched", {
  actor: { type: "user", id: req.userId },    // Repeated
  scope: { type: "organization", id: req.orgId }, // Repeated
});
```

### ✅ Do: End sessions explicitly for manual handles

```typescript
const session = telemetry.session().actor("system", "batch");
try {
  session.emit("batch.started");
  await processBatch();
  session.emit("batch.completed");
} finally {
  await session.end();   // Always end
}
```

***

## Event Design

### ✅ Do: Use descriptive, dot-separated names

```typescript
// ✅ Clear hierarchy, easy to filter
telemetry.emit("igniter.billing.invoice.paid", { ... });
telemetry.emit("igniter.billing.payment.failed", { ... });
telemetry.emit("igniter.auth.login.succeeded", { ... });
```

### ❌ Don't: Use vague or inconsistent names

```typescript
// ❌ Inconsistent, hard to query
telemetry.emit("payment_done", { ... });
telemetry.emit("billingFail", { ... });
telemetry.emit("login", { ... });
```

### ✅ Do: Use `ctx.*` prefix for attribute keys

```typescript
telemetry.emit("order.shipped", {
  attributes: {
    "ctx.order.id": "ord_789",
    "ctx.order.total": 14999,
    "ctx.shipment.carrier": "fedex",
  },
});
```

### ✅ Do: Use past tense for completed events

```typescript
// ✅ Events describe what happened
"succeeded", "failed", "completed", "created", "updated", "deleted", "shipped"
```

### ❌ Don't: Use present tense for completed events

```typescript
// ❌ Ambiguous — did it happen or is it happening?
"create", "update", "delete", "process", "send"
```

***

## Transport Configuration

### ✅ Do: Use multiple transports for different audiences

```typescript
const telemetry = IgniterTelemetry.create()
  .addTransport(LoggerTransportAdapter.create({ logger: pinoLogger }))  // Dev + ops
  .addTransport(SentryTransportAdapter.create({ sentry: Sentry }))       // Errors only
  .addTransport(SlackTransportAdapter.create({                          // Team alerts
    webhookUrl: process.env.SLACK_WEBHOOK_URL!,
    minLevel: "error",
  }))
  .build();
```

### ✅ Do: Filter noisy transports by level

```typescript
// Slack — only errors
const slack = SlackTransportAdapter.create({
  webhookUrl: "...",
  minLevel: "error",
});

// Logger — everything
const logger = LoggerTransportAdapter.create({
  logger: console,
  minLevel: "debug",
});
```

### ❌ Don't: Send everything to every transport

```typescript
// ❌ Slack flooded with debug events, high Sentry costs
const slack = SlackTransportAdapter.create({ webhookUrl: "...", minLevel: "debug" });
```

***

## Sampling

### ✅ Do: Always sample errors

```typescript
sampling: {
  errorRate: 1.0,      // 100% of errors
  always: ["*.error", "*.failed", "security.*"],
}
```

### ✅ Do: Aggressively sample debug in production

```typescript
sampling: {
  debugRate: 0.0,       // 0% in production
  infoRate: 0.05,       // 5% in production
}
```

### ❌ Don't: Run with defaults in production

```typescript
// ❌ 10% info sampling means you lose 90% of operational data
// No `always` patterns means critical events may be dropped
sampling: {}  // Uses defaults: infoRate=0.1, no always patterns
```

***

## Redaction

### ✅ Do: Redact secrets at the edge

```typescript
redaction: {
  denylistKeys: [
    "password", "token", "secret", "authorization",
    "apiKey", "jwt", "cookie",
  ],
}
```

### ✅ Do: Hash PII for correlation without exposure

```typescript
redaction: {
  hashKeys: ["email", "ip", "userId", "phone"],
}
```

### ❌ Don't: Log raw user data

```typescript
// ❌ PII in plain text — violates GDPR, HIPAA
telemetry.emit("user.login", {
  attributes: {
    email: "alice@example.com",       // PII!
    ip: "192.168.1.100",              // PII!
    password: "s3cret!",              // SECRET!
  },
});
```

***

## Error Handling

### ✅ Do: Catch and handle telemetry errors gracefully

```typescript
import { IgniterTelemetryError } from "@igniter-js/telemetry";

try {
  telemetry.emit("unknown.event", { attributes: {} });
} catch (error) {
  if (IgniterTelemetryError.is(error)) {
    console.error(`[${error.code}] ${error.message}`);
    // Don't crash — telemetry errors should never bring down your app
  }
}
```

### ✅ Do: Graceful shutdown

```typescript
process.on("SIGTERM", async () => {
  console.log("Shutting down telemetry...");
  await telemetry.shutdown();
  process.exit(0);
});
```

### ❌ Don't: Let telemetry crash your application

```typescript
// ❌ Uncaught telemetry errors can crash the process
telemetry.emit("unknown.event", { attributes: {} });

// ✅ Always wrap in production
try {
  telemetry.emit(event, input);
} catch (error) {
  // Log but don't crash
}
```

***

## Performance

### ✅ Do: Use `withLogger()` for internal telemetry logging

```typescript
import { IgniterLogger } from "@igniter-js/common";

const telemetry = IgniterTelemetry.create()
  .withLogger(IgniterLogger.create({ name: "telemetry" }))
  .addTransport(loggerAdapter)
  .build();
// Now you see transport init/shutdown logs
```

### ✅ Do: Disable debug in production

```typescript
const logger = LoggerTransportAdapter.create({
  logger: console,
  minLevel: "info",   // No debug in production
});
```

### ❌ Don't: Create a new telemetry instance per request

```typescript
// ❌ Creates a new builder + manager on every request — expensive!
app.get("/api/data", async (req, res) => {
  const telemetry = IgniterTelemetry.create()
    .withService("api")
    .addTransport(loggerAdapter)
    .build();
  telemetry.emit("request.handled");
});

// ✅ Create once, reuse everywhere
const telemetry = IgniterTelemetry.create()
  .withService("api")
  .addTransport(loggerAdapter)
  .build();

app.get("/api/data", async (req, res) => {
  telemetry.emit("request.handled");
});
```

***

## Testing

### ✅ Do: Use Mock adapter in unit tests

```typescript
import { MockTelemetryAdapter } from "@igniter-js/telemetry/adapters";

const mock = MockTelemetryAdapter.create();
const telemetry = IgniterTelemetry.create()
  .withService("test")
  .addTransport(mock)
  .build();

telemetry.emit("user.created", {
  attributes: { "ctx.user.id": "usr_001" },
});

expect(mock.getLastEvent()?.name).toBe("user.created");
expect(mock.getLastEvent()?.attributes).toEqual({
  "ctx.user.id": "usr_001",
});
```

### ✅ Do: Use Memory adapter for integration tests

```typescript
const memory = InMemoryTransportAdapter.create();
const telemetry = IgniterTelemetry.create()
  .addTransport(memory)
  .build();

await handleRequest(req, telemetry);

const events = memory.getEvents();
expect(events).toHaveLength(2);
expect(events[0].name).toBe("request.started");
expect(events[1].name).toBe("request.completed");
```

***

## Quick Reference

| Scenario            | Recommendation                                                    |
| ------------------- | ----------------------------------------------------------------- |
| HTTP handlers       | Scoped execution (`session.run()`)                                |
| Background jobs     | Manual session handle                                             |
| Startup events      | Direct emit                                                       |
| Production sampling | `infoRate: 0.05`, `errorRate: 1.0`, explicit `always` patterns    |
| PII handling        | Denylist secrets, hash emails/IPs                                 |
| Error monitoring    | Sentry adapter for errors, Slack for team alerts                  |
| Testing             | Mock adapter for unit tests, Memory adapter for integration tests |
| Shutdown            | Always call `telemetry.shutdown()` on SIGTERM                     |

***

## Next Steps

* [Troubleshooting](/docs/telemetry/troubleshooting) — Common errors and solutions
* [Framework Integration](/docs/telemetry/framework-integration) — Next.js, Express, and Fastify patterns
* [API Reference](/docs/telemetry/api-reference) — Complete API documentation


---

# Builder Configuration

> Complete reference for the IgniterTelemetry.create() builder — all methods with parameter tables, return types, and verified code examples.
URL: https://igniterjs.com/docs/telemetry/builder-config

## Builder Configuration

The `IgniterTelemetry.create()` builder is a **fluent, immutable configuration chain**. Each method returns a new builder instance — no state is mutated in place. Call `.build()` to create the runtime manager.

***

## Builder Methods Overview

| Method                             | Purpose                        | Required       |
| ---------------------------------- | ------------------------------ | -------------- |
| `.withService(name)`               | Set service name               | Recommended    |
| `.withEnvironment(env)`            | Set environment                | Recommended    |
| `.withVersion(version)`            | Set service version            | Optional       |
| `.addActor(key, options?)`         | Register actor type            | Optional       |
| `.addScope(key, options?)`         | Register scope type            | Optional       |
| `.addEvents(descriptor, options?)` | Register typed events          | Optional       |
| `.addTransport(adapter)`           | Add transport adapter          | At least one   |
| `.withSampling(policy)`            | Configure sampling             | Optional       |
| `.withRedaction(policy)`           | Configure redaction            | Optional       |
| `.withValidation(options)`         | Global validation options      | Optional       |
| `.withLogger(logger)`              | Set internal logger            | Optional       |
| `.build()`                         | Create the manager             | Final step     |
| `.buildConfig()`                   | Build config only (no manager) | For inspection |

***

## `withService(name)`

Sets the service name that appears in every envelope.

```typescript
const telemetry = IgniterTelemetry.create()
  .withService("billing-api")
  .addTransport(loggerAdapter)
  .build();
```

| Parameter | Type     | Description                                       |
| --------- | -------- | ------------------------------------------------- |
| `service` | `string` | Service identifier (e.g., `"my-api"`, `"worker"`) |

<Callout type="info">
  Defaults to `"igniter-app"` if not set. Always set a meaningful service name for production.
</Callout>

***

## `withEnvironment(env)`

Sets the environment name.

```typescript
const telemetry = IgniterTelemetry.create()
  .withEnvironment(process.env.NODE_ENV ?? "development")
  .addTransport(loggerAdapter)
  .build();
```

| Parameter     | Type     | Description                                                     |
| ------------- | -------- | --------------------------------------------------------------- |
| `environment` | `string` | Environment name (`"development"`, `"staging"`, `"production"`) |

<Callout type="info">
  Defaults to `"development"` if not set.
</Callout>

***

## `withVersion(version)`

Sets the service version. Useful for correlating telemetry with deployments.

```typescript
const telemetry = IgniterTelemetry.create()
  .withVersion(process.env.APP_VERSION ?? "unknown")
  .addTransport(loggerAdapter)
  .build();
```

| Parameter | Type     | Description                      |
| --------- | -------- | -------------------------------- |
| `version` | `string` | Version string (e.g., `"1.4.2"`) |

***

## `addActor(key, options?)`

Registers an actor type definition. Actors represent who or what initiated an event.

```typescript
const telemetry = IgniterTelemetry.create()
  .addActor("user", { description: "Authenticated user" })
  .addActor("system", { description: "Automated system action" })
  .addActor("agent", { description: "AI agent" })
  .addTransport(loggerAdapter)
  .build();
```

| Parameter             | Type       | Description                                        |
| --------------------- | ---------- | -------------------------------------------------- |
| `key`                 | `string`   | Actor type identifier (e.g., `"user"`, `"system"`) |
| `options.description` | `string?`  | Human-readable description                         |
| `options.required`    | `boolean?` | Whether this actor is required for all events      |

<Callout type="warn">
  **Duplicate actors throw `TELEMETRY_DUPLICATE_ACTOR`.** Each actor key must be unique across the builder.
</Callout>

***

## `addScope(key, options?)`

Registers a scope type definition. Scopes represent the context or tenant dimension (organization, workspace, project).

```typescript
const telemetry = IgniterTelemetry.create()
  .addScope("organization", { required: true, description: "Tenant organization" })
  .addScope("workspace", { description: "Team workspace" })
  .addScope("project", { description: "Specific project" })
  .addTransport(loggerAdapter)
  .build();
```

| Parameter             | Type       | Description                                    |
| --------------------- | ---------- | ---------------------------------------------- |
| `key`                 | `string`   | Scope type identifier (e.g., `"organization"`) |
| `options.description` | `string?`  | Human-readable description                     |
| `options.required`    | `boolean?` | Whether this scope is required for all events  |

<Callout type="warn">
  **Duplicate scopes throw `TELEMETRY_DUPLICATE_SCOPE`.** Each scope key must be unique across the builder.
</Callout>

***

## `addEvents(descriptor, options?)`

Registers typed event definitions. Accepts the output of `IgniterTelemetryEvents.build()`.

```typescript
const telemetry = IgniterTelemetry.create()
  .addEvents(BillingEvents)
  .addEvents(AuthEvents, { mode: "always", strict: true })
  .addTransport(loggerAdapter)
  .build();
```

| Parameter        | Type                                  | Description                                |
| ---------------- | ------------------------------------- | ------------------------------------------ |
| `descriptor`     | `IgniterTelemetryEventsDescriptor`    | Built event registry                       |
| `options.mode`   | `"development" \| "always" \| "none"` | Validation mode (default: `"development"`) |
| `options.strict` | `boolean`                             | Throw on unknown events (default: `false`) |

***

## `addTransport(adapter)`

Adds a transport adapter. You must add **at least one** transport before calling `.build()`.

```typescript
const telemetry = IgniterTelemetry.create()
  .addTransport(LoggerTransportAdapter.create({ logger: console }))
  .addTransport(HttpTransportAdapter.create({ url: "https://..." }))
  .addTransport(SentryTransportAdapter.create({ sentry: Sentry }))
  .build();
```

| Parameter | Type                               | Description                  |
| --------- | ---------------------------------- | ---------------------------- |
| `adapter` | `IgniterTelemetryTransportAdapter` | A transport adapter instance |

<Callout type="warn">
  **Falsy adapters throw `TELEMETRY_INVALID_TRANSPORT`.** Always pass a valid adapter instance.
</Callout>

***

## `withSampling(policy)`

Configures event sampling to control telemetry volume.

```typescript
const telemetry = IgniterTelemetry.create()
  .withSampling({
    debugRate: 0.01,      // 1% of debug events
    infoRate: 0.1,        // 10% of info events
    warnRate: 1.0,        // 100% of warn events
    errorRate: 1.0,       // 100% of error events
    always: ["*.failed", "security.*"],   // Always sample
    never: ["health.check", "metrics.*"], // Never sample
  })
  .addTransport(loggerAdapter)
  .build();
```

| Field       | Type       | Default | Description                          |
| ----------- | ---------- | ------- | ------------------------------------ |
| `debugRate` | `number`   | `0.01`  | Sampling rate for debug events (0–1) |
| `infoRate`  | `number`   | `0.1`   | Sampling rate for info events (0–1)  |
| `warnRate`  | `number`   | `1.0`   | Sampling rate for warn events (0–1)  |
| `errorRate` | `number`   | `1.0`   | Sampling rate for error events (0–1) |
| `always`    | `string[]` | `[]`    | Glob patterns always sampled         |
| `never`     | `string[]` | `[]`    | Glob patterns never sampled          |

***

## `withRedaction(policy)`

Configures PII redaction applied before events reach transports.

```typescript
const telemetry = IgniterTelemetry.create()
  .withRedaction({
    denylistKeys: ["password", "token", "authorization"],
    hashKeys: ["email", "ip", "userId"],
    maxStringLength: 5000,
  })
  .addTransport(loggerAdapter)
  .build();
```

| Field             | Type       | Default | Description                                  |
| ----------------- | ---------- | ------- | -------------------------------------------- |
| `denylistKeys`    | `string[]` | `[]`    | Keys to completely remove (case-insensitive) |
| `hashKeys`        | `string[]` | `[]`    | Keys to SHA-256 hash (for correlation)       |
| `maxStringLength` | `number`   | `5000`  | Maximum string length before truncation      |

***

## `withValidation(options)`

Sets global event validation options. Overrides per-registry defaults.

```typescript
const telemetry = IgniterTelemetry.create()
  .withValidation({ mode: "always", strict: true })
  .addTransport(loggerAdapter)
  .build();
```

| Field    | Type                                  | Default         | Description             |
| -------- | ------------------------------------- | --------------- | ----------------------- |
| `mode`   | `"development" \| "always" \| "none"` | `"development"` | When to validate        |
| `strict` | `boolean`                             | `false`         | Throw on unknown events |

***

## `withLogger(logger)`

Sets an internal logger for the telemetry manager to report its own operational events (init, transport errors, etc.).

```typescript
import { IgniterLogger } from "@igniter-js/common";

const telemetry = IgniterTelemetry.create()
  .withLogger(IgniterLogger.create({ name: "telemetry" }))
  .addTransport(loggerAdapter)
  .build();
```

| Parameter | Type            | Description                               |
| --------- | --------------- | ----------------------------------------- |
| `logger`  | `IgniterLogger` | Logger instance from `@igniter-js/common` |

***

## `build()`

Creates the runtime `IgniterTelemetryManager` instance. This is the **final method** in the chain.

```typescript
const telemetry = IgniterTelemetry.create()
  .withService("api")
  .addTransport(loggerAdapter)
  .build();  // => IgniterTelemetryManager
```

During `.build()`:

1. Merges config with defaults
2. Logs initialization info (if logger is set)
3. Creates the manager instance
4. Initializes all transports (`adapter.init()`)

***

## `buildConfig()`

Builds the configuration object without creating the runtime manager. Useful for inspection or testing.

```typescript
const config = IgniterTelemetry.create()
  .withService("api")
  .addEvents(BillingEvents)
  .withSampling({ errorRate: 1.0 })
  .buildConfig();

console.log(config.service);     // "api"
console.log(config.sampling);    // { debugRate: 0.01, infoRate: 0.1, ... }
```

| Returns  | Type                     | Description                                 |
| -------- | ------------------------ | ------------------------------------------- |
| `config` | `IgniterTelemetryConfig` | Resolved configuration object with defaults |

***

## Global Validation

You can set validation globally via `.withValidation()`, which applies to all events:

```typescript
const telemetry = IgniterTelemetry.create()
  .withValidation({ mode: "always", strict: true })   // Global
  .addEvents(BillingEvents, { mode: "development" })   // Per-registry override
  .addEvents(AuthEvents)                                // Inherits global
  .addTransport(loggerAdapter)
  .build();
```

Per-registry options override global options for that specific registry.

***

## Next Steps

* [Emitting Events](/docs/telemetry/emitting-events) — Three emit modes, attributes, levels, and errors
* [Sessions](/docs/telemetry/sessions) — Session lifecycle and scoped execution
* [Validation](/docs/telemetry/validation) — Deep dive into event validation


---

# Defining Events

> Create typed event registries with IgniterTelemetryEvents — namespaces, groups, Zod schemas, and registry descriptors for full TypeScript inference.
URL: https://igniterjs.com/docs/telemetry/defining-events

## Defining Events

`IgniterTelemetryEvents` is the **typed event registry builder**. It creates namespaced, schema-validated event definitions that feed into the telemetry builder — giving you autocompletion on `emit()` calls and optional runtime validation.

<Callout type="info">
  Typed events are **optional**. You can emit any string event name without a registry. Registries give you autocompletion, documentation, and validation when you need it.
</Callout>

***

## Basic Structure

Every event registry starts with a namespace and contains events or groups:

```typescript
import { IgniterTelemetryEvents } from "@igniter-js/telemetry";
import { z } from "zod";

const MyEvents = IgniterTelemetryEvents
  .namespace("myapp.feature")     // 1. Define namespace
  .event("action.done", schema)   // 2. Add flat events
  .group("subfeature", (g) =>     // 3. Add nested groups
    g.event("start", schema)
     .event("complete", schema)
  )
  .build();                       // 4. Build the descriptor
```

***

## Flat Events

Define individual, non-grouped events under a namespace:

```typescript
import { z } from "zod";
import { IgniterTelemetryEvents } from "@igniter-js/telemetry";

const AuthEvents = IgniterTelemetryEvents
  .namespace("igniter.auth")
  .event("login.succeeded", z.object({
    "ctx.user.id": z.string(),
    "ctx.login.method": z.enum(["password", "oauth", "magic_link"]),
    "ctx.login.ip": z.string(),
  }))
  .event("login.failed", z.object({
    "ctx.user.id": z.string().optional(),
    "ctx.login.method": z.string(),
    "ctx.login.reason": z.string(),
  }))
  .event("logout", z.object({
    "ctx.user.id": z.string(),
    "ctx.session.duration_seconds": z.number(),
  }))
  .build();
```

Emitting these events gives autocompletion:

```typescript
telemetry.emit("igniter.auth.login.succeeded", {
  attributes: {
    "ctx.user.id": "usr_123",
    "ctx.login.method": "oauth",
    "ctx.login.ip": "192.168.1.1",
  },
});
```

***

## Grouped Events

Organize related events into groups for logical hierarchy and better autocompletion:

```typescript
const OrderEvents = IgniterTelemetryEvents
  .namespace("igniter.orders")
  .group("checkout", (g) =>
    g
      .event("started", z.object({
        "ctx.cart.id": z.string(),
        "ctx.cart.item_count": z.number(),
      }))
      .event("completed", z.object({
        "ctx.order.id": z.string(),
        "ctx.order.total": z.number(),
      }))
      .event("abandoned", z.object({
        "ctx.cart.id": z.string(),
        "ctx.cart.elapsed_seconds": z.number(),
      }))
  )
  .group("fulfillment", (g) =>
    g
      .event("picked", z.object({
        "ctx.order.id": z.string(),
        "ctx.warehouse.id": z.string(),
      }))
      .event("shipped", z.object({
        "ctx.order.id": z.string(),
        "ctx.shipment.tracking": z.string(),
      }))
      .event("delivered", z.object({
        "ctx.order.id": z.string(),
        "ctx.delivery.timestamp": z.string(),
      }))
  )
  .build();
```

Grouped events use dot-separated names:

```typescript
telemetry.emit("igniter.orders.checkout.completed", {
  attributes: {
    "ctx.order.id": "ord_456",
    "ctx.order.total": 8999,
  },
});
```

***

## Schema Libraries

The event builder accepts Zod schemas, StandardSchemaV1 schemas, or any schema object with `parse`/`safeParse` methods.

<Callout type="info">
  Zod is used in all examples but is **not bundled**. You control which schema library to use — just make sure it implements `parse()` or `safeParse()`.
</Callout>

```typescript
// Zod (recommended)
import { z } from "zod";

const schema = z.object({
  "ctx.user.id": z.string(),
});
```

***

## Adding Events to the Builder

Use `.addEvents()` to register event descriptors with the telemetry builder:

```typescript
const telemetry = IgniterTelemetry.create()
  .withService("api")
  .addEvents(AuthEvents)            // First registry
  .addEvents(OrderEvents)           // Second registry
  .addEvents(BillingEvents, {       // With validation options
    mode: "always",
    strict: true,
  })
  .addTransport(loggerAdapter)
  .build();
```

### Validation Options

`addEvents()` accepts optional validation options per registry:

```typescript
interface IgniterTelemetryEventsValidationOptions {
  mode?: "development" | "always" | "none";  // default: "development"
  strict?: boolean;                            // default: false
}
```

| Option                | Description                                                   |
| --------------------- | ------------------------------------------------------------- |
| `mode: "development"` | Validate only when `NODE_ENV !== "production"`                |
| `mode: "always"`      | Always validate — throw on schema mismatch even in production |
| `mode: "none"`        | Never validate — events pass through regardless               |
| `strict: true`        | Throw on unknown event names (events not in any registry)     |

***

## Using the Descriptor Helpers

The built descriptor exposes helpers for getting typed keys and schemas:

```typescript
const BillingEvents = IgniterTelemetryEvents
  .namespace("igniter.billing")
  .event("cycle.started", z.object({ "ctx.cycle.id": z.string() }))
  .build();

// Get the full event key with namespace
const key = BillingEvents.get.key("cycle.started");
// => "igniter.billing.cycle.started"

// Get the schema for a specific event
const schema = BillingEvents.get.schema("cycle.started");
// => z.ZodObject<{ "ctx.cycle.id": z.ZodString }>

// Type inference
type BillingRegistry = typeof BillingEvents.$Infer.registry;
type BillingKeys = typeof BillingEvents.$Infer.keys;
// => "cycle.started"
```

***

## Multiple Namespaces

You can register multiple namespaces on the same telemetry instance:

```typescript
const telemetry = IgniterTelemetry.create()
  .withService("platform")
  .addEvents(AuthEvents)       // namespace: "igniter.auth"
  .addEvents(OrderEvents)      // namespace: "igniter.orders"
  .addEvents(BillingEvents)    // namespace: "igniter.billing"
  .addTransport(loggerAdapter)
  .build();

// All namespaces are available on emit()
telemetry.emit("igniter.auth.login.succeeded", { ... });
telemetry.emit("igniter.orders.checkout.completed", { ... });
telemetry.emit("igniter.billing.invoice.paid", { ... });
```

<Callout type="warn">
  **Duplicate namespaces throw an error.** If you try to register two descriptors with the same namespace, `TELEMETRY_DUPLICATE_NAMESPACE` is thrown. Use multiple events/groups within a single namespace instead.
</Callout>

***

## Naming Conventions

Recommended event naming patterns:

| Pattern                     | Example                         | Use Case              |
| --------------------------- | ------------------------------- | --------------------- |
| `namespace.group.action`    | `igniter.jobs.job.completed`    | Grouped domain events |
| `namespace.verb.past_tense` | `igniter.auth.login.succeeded`  | Lifecycle events      |
| `namespace.verb.present`    | `igniter.billing.cycle.started` | Process start events  |
| `namespace.noun.action`     | `igniter.mail.recipient.added`  | Entity events         |

### Key Guidelines

* Use **dot-separated names** for hierarchy (`igniter.jobs.worker.started`)
* Use **past tense** for completed actions (`succeeded`, `failed`, `completed`)
* Use **`ctx.*` prefix** for attribute keys (`ctx.user.id`, `ctx.order.total`)
* Use **lowercase** for all event names and attribute keys
* Keep event names **descriptive** — prefer `payment.intent.created` over `pay_created`

***

## Next Steps

* [Builder Configuration](/docs/telemetry/builder-config) — All builder methods and options
* [Emitting Events](/docs/telemetry/emitting-events) — Attributes, levels, errors, and source metadata
* [Validation](/docs/telemetry/validation) — Event validation modes and strict mode


---

# Emitting Events

> Master the three telemetry emit modes — direct, session, and scoped execution. Learn attributes, levels, error details, source metadata, and event envelope structure.
URL: https://igniterjs.com/docs/telemetry/emitting-events

## Emitting Events

The `emit()` method is the primary way to send telemetry events. It supports three distinct patterns — choose the right one for each scenario.

***

## The Three Emit Modes

### Mode A: Direct Emit

No session required. Each event stands alone. Best for background jobs, startup events, or one-off emissions.

```typescript
telemetry.emit("service.booted", {
  attributes: { "ctx.service.startup_ms": 142 },
});

telemetry.emit("cache.warmed", {
  level: "debug",
  attributes: { "ctx.cache.keys_loaded": 1200 },
});
```

### Mode B: Manual Session Handle

Create a session, bind actor/scope, emit events, and end it. Best for request handlers that need explicit session control.

```typescript
const session = telemetry.session()
  .actor("user", "usr_123", { role: "admin" })
  .scope("organization", "org_456")
  .attributes({ "ctx.request.id": "req_abc" });

session.emit("user.profile.updated", {
  attributes: { "ctx.user.field": "email" },
});

session.emit("user.notification.sent", {
  attributes: { "ctx.notification.type": "email" },
});

await session.end();
```

### Mode C: Scoped Execution

All events inside `run()` automatically inherit the session context via `AsyncLocalStorage`. Best for HTTP request handlers — no manual context passing.

```typescript
await telemetry.session()
  .actor("user", "usr_123")
  .scope("organization", "org_456")
  .run(async () => {
    // These events automatically carry user + org context
    telemetry.emit("request.started", { ... });
    await doWork();
    telemetry.emit("request.completed", { ... });
  });
```

<Callout type="info">
  **Mode C is the recommended approach** for request-response cycles. It uses Node.js `AsyncLocalStorage` to maintain session context across async boundaries without explicit passing.
</Callout>

***

## Event Levels

Telemetry supports five severity levels, matching OpenTelemetry conventions:

| Level   | Typical Use                                  | Default Sampling |
| ------- | -------------------------------------------- | ---------------- |
| `debug` | Verbose diagnostic information               | 1%               |
| `info`  | General operational events                   | 10%              |
| `warn`  | Unexpected but handled situations            | 100%             |
| `error` | Failures that need attention                 | 100%             |
| `fatal` | Critical failures requiring immediate action | 100%             |

```typescript
// Default level is "info"
telemetry.emit("user.login.succeeded", { ... });

// Explicit levels
telemetry.emit("cache.miss", { level: "debug", ... });
telemetry.emit("payment.processed", { level: "info", ... });
telemetry.emit("rate_limit.approaching", { level: "warn", ... });
telemetry.emit("payment.failed", { level: "error", ... });
telemetry.emit("database.corrupted", { level: "fatal", ... });
```

***

## Attributes

Attributes are a flat key-value map attached to every event. They provide the structured data that makes telemetry queryable.

### Naming Convention

Use `ctx.` prefix with dot-separated names for consistency:

```typescript
telemetry.emit("order.shipped", {
  attributes: {
    "ctx.order.id": "ord_789",
    "ctx.order.total": 14999,
    "ctx.order.currency": "usd",
    "ctx.shipment.carrier": "fedex",
    "ctx.shipment.tracking_number": "1Z999AA10123456784",
    "ctx.shipment.weight_kg": 2.3,
  },
});
```

### Merging with Session Attributes

Event attributes are merged with session attributes — event-level values override session values:

```typescript
const session = telemetry.session()
  .attributes({
    "ctx.request.id": "req_abc",
    "ctx.request.method": "POST",
  });

// Event attributes override session attributes
session.emit("request.completed", {
  attributes: {
    "ctx.request.status": 200,         // Added
    "ctx.request.method": "GET",       // Overrides session "POST"
  },
});
// Result: { "ctx.request.id": "req_abc", "ctx.request.method": "GET", "ctx.request.status": 200 }
```

***

## Error Details

Pass structured error information alongside events using the `error` field:

```typescript
telemetry.emit("payment.failed", {
  level: "error",
  error: {
    name: "PaymentError",
    message: "Card declined by issuer",
    code: "CARD_DECLINED",
    stack: undefined,  // Optional stack trace
  },
  attributes: {
    "ctx.payment.id": "pay_456",
    "ctx.payment.provider": "stripe",
  },
});
```

### Error Object Structure

| Field     | Type      | Description                               |
| --------- | --------- | ----------------------------------------- |
| `name`    | `string`  | Error class name (e.g., `"PaymentError"`) |
| `message` | `string`  | Human-readable error description          |
| `code`    | `string?` | Machine-readable error code               |
| `stack`   | `string?` | Stack trace (optional)                    |

<Callout type="info">
  Error details are preserved in the envelope and can be used by transports like Sentry, Slack, or Discord for rich error reporting.
</Callout>

***

## Source Metadata

Tag events with their origin in the codebase using the `source` field:

```typescript
telemetry.emit("feature.flag.evaluated", {
  source: {
    causer: "@myapp/flags",
    file: "flags/evaluate.ts",
    line: 142,
  },
  attributes: {
    "ctx.flag.key": "new-dashboard",
    "ctx.flag.value": true,
  },
});
```

| Field    | Type      | Description                   |
| -------- | --------- | ----------------------------- |
| `causer` | `string?` | Package or module responsible |
| `file`   | `string?` | Source file path              |
| `line`   | `number?` | Line number                   |

***

## The Event Envelope

Every `emit()` call produces an envelope — a normalized payload sent to all transports:

```typescript
interface IgniterTelemetryEnvelope {
  name: string;              // Event name
  time: string;              // ISO 8601 timestamp
  level: string;             // debug | info | warn | error | fatal
  service: string;           // From withService()
  environment: string;       // From withEnvironment()
  version?: string;          // From withVersion()
  sessionId: string;         // Auto-generated or from session
  actor?: {                  // From session or emit input
    type: string;
    id?: string;
    tags?: Record<string, unknown>;
  };
  scope?: {                  // From session or emit input
    type: string;
    id: string;
    tags?: Record<string, unknown>;
  };
  attributes?: Record<string, unknown>;  // Redacted
  error?: {
    name: string;
    message: string;
    code?: string;
    stack?: string;
  };
  source?: {
    causer?: string;
    file?: string;
    line?: number;
  };
}
```

***

## Emit with Custom Session ID

Override the auto-generated session ID:

```typescript
telemetry.emit("request.started", {
  sessionId: "trace_abc_123",  // Custom session ID
  attributes: {
    "ctx.request.path": "/api/orders",
  },
});
```

***

## Emit with Custom Timestamp

Override the auto-generated timestamp:

```typescript
telemetry.emit("historical.event", {
  time: "2024-01-15T10:30:00.000Z",  // Custom timestamp
  attributes: {
    "ctx.event.recorded_at": "2024-01-15T10:30:00.000Z",
  },
});
```

***

## Flushing and Shutdown

For transports that buffer events (like HTTP with retries), you can explicitly flush:

```typescript
// Flush pending events without shutting down
await telemetry.flush();

// Graceful shutdown: flush + clean up
await telemetry.shutdown();
```

<Callout type="warn">
  **Always call `shutdown()`** before process exit. Transports may have buffered events or open connections that need cleanup.
</Callout>

***

## Next Steps

* [Sessions](/docs/telemetry/sessions) — Deep dive into session lifecycle and scoped execution
* [Sampling & Redaction](/docs/telemetry/sampling-redaction) — Control volume and protect PII
* [Adapters](/docs/telemetry/adapters) — Route events to different destinations


---

# Framework Integration

> Integrate @igniter-js/telemetry with Next.js (App Router + Middleware), Express, and Fastify. Production-ready patterns with session correlation per request.
URL: https://igniterjs.com/docs/telemetry/framework-integration

## Framework Integration

Telemetry is framework-agnostic, but these patterns make it feel native in popular frameworks. All examples are verified and production-ready.

***

## Next.js (App Router)

### Singleton Telemetry Instance

Create a shared instance once:

```typescript
// lib/telemetry.ts
import { IgniterTelemetry } from "@igniter-js/telemetry";
import {
  LoggerTransportAdapter,
  SentryTransportAdapter,
} from "@igniter-js/telemetry/adapters";
import * as Sentry from "@sentry/nextjs";

const createTelemetry = () => {
  if (process.env.NODE_ENV === "development") {
    return IgniterTelemetry.create()
      .withService("my-next-app")
      .withEnvironment("development")
      .addTransport(LoggerTransportAdapter.create({
        logger: console,
        format: "pretty",
      }))
      .build();
  }

  Sentry.init({ dsn: process.env.SENTRY_DSN });

  return IgniterTelemetry.create()
    .withService("my-next-app")
    .withEnvironment("production")
    .withVersion(process.env.NEXT_PUBLIC_APP_VERSION ?? "0.0.0")
    .addActor("user")
    .addScope("organization")
    .addTransport(LoggerTransportAdapter.create({
      logger: console,
      format: "json",
      minLevel: "info",
    }))
    .addTransport(SentryTransportAdapter.create({ sentry: Sentry }))
    .withSampling({
      debugRate: 0.0,
      infoRate: 0.1,
      warnRate: 1.0,
      errorRate: 1.0,
    })
    .withRedaction({
      denylistKeys: ["password", "token", "authorization"],
      hashKeys: ["email", "ip"],
    })
    .build();
};

// Singleton — avoid globalThis pattern in Next.js
declare global {
  var __telemetry: ReturnType<typeof createTelemetry> | undefined;
}
const telemetry = globalThis.__telemetry ?? createTelemetry();
if (process.env.NODE_ENV !== "production") globalThis.__telemetry = telemetry;

export { telemetry };
```

### Middleware: Session Per Request

```typescript
// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { telemetry } from "@/lib/telemetry";

export async function middleware(request: NextRequest) {
  const userId = request.headers.get("x-user-id") ?? "anonymous";
  const orgId = request.headers.get("x-org-id") ?? "unknown";

  return telemetry.session()
    .actor("user", userId)
    .scope("organization", orgId)
    .attributes({
      "ctx.request.method": request.method,
      "ctx.request.path": request.nextUrl.pathname,
      "ctx.request.ip": request.ip ?? "unknown",
    })
    .run(async () => {
      telemetry.emit("request.started", {
        attributes: { "ctx.request.path": request.nextUrl.pathname },
      });

      const response = NextResponse.next();

      telemetry.emit("request.completed", {
        attributes: { "ctx.request.status": response.status },
      });

      return response;
    });
}

export const config = {
  matcher: "/api/:path*",
};
```

### API Route Handler

```typescript
// app/api/orders/[id]/route.ts
import { NextRequest, NextResponse } from "next/server";
import { telemetry } from "@/lib/telemetry";

export async function GET(
  req: NextRequest,
  { params }: { params: { id: string } },
) {
  try {
    // Session context auto-inherited from middleware
    telemetry.emit("order.fetch.started", {
      attributes: { "ctx.order.id": params.id },
    });

    const order = await fetchOrder(params.id);

    telemetry.emit("order.fetch.completed", {
      attributes: {
        "ctx.order.id": params.id,
        "ctx.order.status": order.status,
      },
    });

    return NextResponse.json(order);
  } catch (error) {
    telemetry.emit("order.fetch.failed", {
      level: "error",
      error: {
        name: error instanceof Error ? error.name : "Error",
        message: error instanceof Error ? error.message : String(error),
      },
      attributes: { "ctx.order.id": params.id },
    });

    return NextResponse.json(
      { error: "Failed to fetch order" },
      { status: 500 },
    );
  }
}
```

### Server Action

```typescript
// app/actions/create-invoice.ts
"use server";

import { telemetry } from "@/lib/telemetry";

export async function createInvoice(formData: FormData) {
  return telemetry.session()
    .actor("user", formData.get("userId") as string)
    .scope("organization", formData.get("orgId") as string)
    .run(async () => {
      telemetry.emit("igniter.billing.invoice.created", {
        attributes: {
          "ctx.invoice.amount": Number(formData.get("amount")),
          "ctx.invoice.currency": formData.get("currency") as string,
        },
      });

      // ... create invoice logic ...

      return { success: true };
    });
}
```

### Graceful Shutdown (Next.js)

```typescript
// instrumentation.ts
import { telemetry } from "@/lib/telemetry";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    process.on("SIGTERM", async () => {
      await telemetry.shutdown();
    });

    process.on("SIGINT", async () => {
      await telemetry.shutdown();
    });
  }
}
```

***

## Express

### Singleton Instance

```typescript
// lib/telemetry.ts
import { IgniterTelemetry } from "@igniter-js/telemetry";
import { LoggerTransportAdapter } from "@igniter-js/telemetry/adapters";

export const telemetry = IgniterTelemetry.create()
  .withService("express-api")
  .withEnvironment(process.env.NODE_ENV ?? "development")
  .addActor("user")
  .addScope("organization")
  .addTransport(LoggerTransportAdapter.create({
    logger: console,
    format: process.env.NODE_ENV === "production" ? "json" : "pretty",
  }))
  .build();
```

### Request Middleware

```typescript
// middleware/telemetry.ts
import { Request, Response, NextFunction } from "express";
import { telemetry } from "../lib/telemetry";

export function telemetryMiddleware(
  req: Request,
  res: Response,
  next: NextFunction,
) {
  const userId = (req.headers["x-user-id"] as string) ?? "anonymous";
  const orgId = (req.headers["x-org-id"] as string) ?? "unknown";

  telemetry.session()
    .actor("user", userId)
    .scope("organization", orgId)
    .attributes({
      "ctx.request.method": req.method,
      "ctx.request.path": req.path,
      "ctx.request.ip": req.ip,
    })
    .run(async () => {
      telemetry.emit("request.started", {
        attributes: { "ctx.request.path": req.path },
      });

      const startTime = Date.now();

      // Track response completion
      res.on("finish", () => {
        const duration = Date.now() - startTime;
        telemetry.emit("request.completed", {
          attributes: {
            "ctx.request.status": res.statusCode,
            "ctx.request.duration_ms": duration,
          },
        });
      });

      next();
    });
}
```

### Route Handler

```typescript
// routes/orders.ts
import { Router } from "express";
import { telemetry } from "../lib/telemetry";

const router = Router();

router.get("/:id", async (req, res) => {
  try {
    // Session context auto-inherited from middleware
    telemetry.emit("order.fetch.started", {
      attributes: { "ctx.order.id": req.params.id },
    });

    const order = await fetchOrder(req.params.id);

    telemetry.emit("order.fetch.completed", {
      attributes: {
        "ctx.order.id": req.params.id,
        "ctx.order.status": order.status,
      },
    });

    res.json(order);
  } catch (error) {
    telemetry.emit("order.fetch.failed", {
      level: "error",
      error: {
        name: error instanceof Error ? error.name : "Error",
        message: error instanceof Error ? error.message : String(error),
      },
    });

    res.status(500).json({ error: "Failed to fetch order" });
  }
});

export default router;
```

### App Entry Point

```typescript
// app.ts
import express from "express";
import { telemetry } from "./lib/telemetry";
import { telemetryMiddleware } from "./middleware/telemetry";
import ordersRouter from "./routes/orders";

const app = express();

// Apply telemetry middleware before routes
app.use(telemetryMiddleware);

app.use("/api/orders", ordersRouter);

const server = app.listen(3000, () => {
  telemetry.emit("service.booted", {
    attributes: { "ctx.service.port": 3000 },
  });
});

// Graceful shutdown
process.on("SIGTERM", async () => {
  console.log("Shutting down...");
  server.close(async () => {
    await telemetry.shutdown();
    process.exit(0);
  });
});
```

***

## Fastify

### Singleton Instance

```typescript
// lib/telemetry.ts
import { IgniterTelemetry } from "@igniter-js/telemetry";
import { LoggerTransportAdapter } from "@igniter-js/telemetry/adapters";

export const telemetry = IgniterTelemetry.create()
  .withService("fastify-api")
  .withEnvironment(process.env.NODE_ENV ?? "development")
  .addActor("user")
  .addScope("organization")
  .addTransport(LoggerTransportAdapter.create({
    logger: console,
    format: "json",
  }))
  .build();
```

### Plugin (Hook-Based)

```typescript
// plugins/telemetry.ts
import { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
import fp from "fastify-plugin";
import { telemetry } from "../lib/telemetry";

async function telemetryPlugin(fastify: FastifyInstance) {
  // onRequest hook — enters session context
  fastify.addHook("onRequest", async (request, reply) => {
    const userId = (request.headers["x-user-id"] as string) ?? "anonymous";
    const orgId = (request.headers["x-org-id"] as string) ?? "unknown";

    // Store session state for the request lifecycle
    (request as any).__telemetrySession = telemetry.session()
      .actor("user", userId)
      .scope("organization", orgId)
      .attributes({
        "ctx.request.method": request.method,
        "ctx.request.path": request.url,
        "ctx.request.ip": request.ip,
      });

    telemetry.emit("request.started", {
      attributes: { "ctx.request.path": request.url },
    });
  });

  // onResponse hook — emit completion
  fastify.addHook("onResponse", async (request, reply) => {
    const session = (request as any).__telemetrySession;
    if (session) {
      session.emit("request.completed", {
        attributes: {
          "ctx.request.status": reply.statusCode,
          "ctx.request.duration_ms": reply.elapsedTime,
        },
      });
      await session.end();
    }
  });

  // Decorate with emit helper
  fastify.decorateRequest("emitTelemetry", function (
    this: FastifyRequest,
    name: string,
    input?: Record<string, unknown>,
  ) {
    const session = (this as any).__telemetrySession;
    if (session) {
      session.emit(name, input as any);
    } else {
      telemetry.emit(name, input as any);
    }
  });
}

export default fp(telemetryPlugin, { name: "telemetry" });
```

### Route Handler

```typescript
// routes/orders.ts
import { FastifyInstance } from "fastify";

export default async function ordersRoutes(fastify: FastifyInstance) {
  fastify.get("/api/orders/:id", async (request, reply) => {
    const { id } = request.params as { id: string };

    try {
      (request as any).emitTelemetry("order.fetch.started", {
        attributes: { "ctx.order.id": id },
      });

      const order = await fetchOrder(id);

      (request as any).emitTelemetry("order.fetch.completed", {
        attributes: { "ctx.order.id": id, "ctx.order.status": order.status },
      });

      return order;
    } catch (error) {
      (request as any).emitTelemetry("order.fetch.failed", {
        level: "error",
        error: {
          name: error instanceof Error ? error.name : "Error",
          message: error instanceof Error ? error.message : String(error),
        },
      });

      reply.status(500).send({ error: "Failed to fetch order" });
    }
  });
}
```

### App Entry

```typescript
// app.ts
import Fastify from "fastify";
import { telemetry } from "./lib/telemetry";
import telemetryPlugin from "./plugins/telemetry";
import ordersRoutes from "./routes/orders";

const fastify = Fastify({ logger: true });

// Register telemetry plugin
await fastify.register(telemetryPlugin);

// Register routes
await fastify.register(ordersRoutes);

// Start
await fastify.listen({ port: 3000 });

telemetry.emit("service.booted", {
  attributes: { "ctx.service.port": 3000 },
});

// Graceful shutdown
process.on("SIGTERM", async () => {
  await telemetry.shutdown();
  await fastify.close();
  process.exit(0);
});
```

***

## Background Jobs

For worker processes, background jobs, and cron handlers — use manual session handles:

```typescript
// workers/invoice-generator.ts
import { telemetry } from "../lib/telemetry";

export async function generateInvoices() {
  const session = telemetry.session()
    .actor("system", "invoice-generator", { schedule: "daily" });

  try {
    session.emit("batch.invoices.started");

    const invoices = await fetchPendingInvoices();

    for (const invoice of invoices) {
      await telemetry.session()
        .scope("organization", invoice.orgId)
        .run(async () => {
          session.emit("igniter.billing.invoice.created", {
            attributes: {
              "ctx.invoice.id": invoice.id,
              "ctx.invoice.amount": invoice.amount,
            },
          });
        });
    }

    session.emit("batch.invoices.completed", {
      attributes: { "ctx.batch.count": invoices.length },
    });
  } catch (error) {
    session.emit("batch.invoices.failed", {
      level: "error",
      error: {
        name: error instanceof Error ? error.name : "Error",
        message: error instanceof Error ? error.message : String(error),
      },
    });
  } finally {
    await session.end();
  }
}
```

***

## Next Steps

* [Best Practices](/docs/telemetry/best-practices) — Production-tested patterns
* [Sessions](/docs/telemetry/sessions) — Deep dive into session lifecycle
* [API Reference](/docs/telemetry/api-reference) — Complete API documentation


---

# Getting Started

> Build a complete typed telemetry setup from zero to production-ready. Define events with Zod, configure transports, emit with sessions, and shut down gracefully.
URL: https://igniterjs.com/docs/telemetry/getting-started

## Getting Started

This guide walks through building a **production-ready telemetry setup** for a billing API — from defining typed events to emitting with sessions and shutting down gracefully.

By the end, you'll have a telemetry instance with typed events, two transports (Logger + Sentry), sampling, redaction, and session correlation.

***

## Step 1 — Define Typed Events

Use `IgniterTelemetryEvents` to create namespaced, schema-validated event registries. Groups help organize related events.

```typescript
// telemetry/events.ts
import { IgniterTelemetryEvents } from "@igniter-js/telemetry";
import { z } from "zod";

export const BillingEvents = IgniterTelemetryEvents
  .namespace("igniter.billing")
  .group("invoice", (g) =>
    g
      .event("created", z.object({
        "ctx.invoice.id": z.string(),
        "ctx.invoice.amount": z.number(),
        "ctx.invoice.currency": z.string().length(3),
      }))
      .event("paid", z.object({
        "ctx.invoice.id": z.string(),
        "ctx.invoice.amount": z.number(),
        "ctx.invoice.paid_at": z.string(),
      }))
      .event("voided", z.object({
        "ctx.invoice.id": z.string(),
        "ctx.invoice.reason": z.string(),
      }))
  )
  .group("payment", (g) =>
    g
      .event("succeeded", z.object({
        "ctx.payment.id": z.string(),
        "ctx.payment.provider": z.string(),
        "ctx.payment.amount": z.number(),
      }))
      .event("failed", z.object({
        "ctx.payment.id": z.string(),
        "ctx.payment.provider": z.string(),
        "ctx.payment.error_code": z.string(),
      }))
  )
  .build();
```

<Callout type="info">
  Zod is optional — you can emit untyped events too. But typed registries give you autocompletion on event names and runtime validation if enabled.
</Callout>

***

## Step 2 — Create the Telemetry Instance

The builder chains are immutable — each method returns a new builder instance. Configure everything before calling `.build()`.

```typescript
// telemetry/instance.ts
import { IgniterTelemetry } from "@igniter-js/telemetry";
import {
  LoggerTransportAdapter,
  SentryTransportAdapter,
} from "@igniter-js/telemetry/adapters";
import * as Sentry from "@sentry/node";
import { BillingEvents } from "./events";

Sentry.init({ dsn: process.env.SENTRY_DSN });

export const telemetry = IgniterTelemetry.create()
  .withService("billing-api")
  .withEnvironment(process.env.NODE_ENV ?? "development")
  .withVersion(process.env.APP_VERSION ?? "0.0.0")
  .addActor("user", { description: "Authenticated user" })
  .addActor("system", { description: "Automated system action" })
  .addScope("organization", { required: true, description: "Tenant organization" })
  .addScope("workspace", { description: "Team workspace" })
  .addEvents(BillingEvents, { mode: "development" })
  .addTransport(LoggerTransportAdapter.create({
    logger: console,
    format: "json",
    minLevel: "info",
  }))
  .addTransport(SentryTransportAdapter.create({ sentry: Sentry }))
  .withSampling({
    debugRate: 0.01,
    infoRate: 0.1,
    warnRate: 1.0,
    errorRate: 1.0,
    always: ["*.failed", "*.error"],
    never: ["health.check"],
  })
  .withRedaction({
    denylistKeys: ["password", "secret", "authorization"],
    hashKeys: ["email", "ip", "userAgent"],
    maxStringLength: 5000,
  })
  .build();
```

***

## Step 3 — Emit Events (Three Modes)

### Mode A: Direct Emit

Simplest. Use for one-off events without session context.

```typescript
// Emit typed events with autocompletion
telemetry.emit("igniter.billing.invoice.created", {
  attributes: {
    "ctx.invoice.id": "inv_789",
    "ctx.invoice.amount": 2999,
    "ctx.invoice.currency": "usd",
  },
});

// Emit with error details
telemetry.emit("igniter.billing.payment.failed", {
  level: "error",
  error: {
    name: "PaymentError",
    message: "Card declined",
    code: "CARD_DECLINED",
  },
  attributes: {
    "ctx.payment.id": "pay_456",
    "ctx.payment.provider": "stripe",
    "ctx.payment.error_code": "card_declined",
  },
});
```

### Mode B: Manual Session Handle

Create a session, bind context, emit multiple events, and end it.

```typescript
const session = telemetry.session()
  .actor("user", "usr_123", { role: "admin" })
  .scope("organization", "org_456", { plan: "enterprise" })
  .attributes({ "ctx.request.id": "req_abc" });

session.emit("igniter.billing.invoice.created", {
  attributes: {
    "ctx.invoice.id": "inv_001",
    "ctx.invoice.amount": 5000,
    "ctx.invoice.currency": "usd",
  },
});

session.emit("igniter.billing.payment.succeeded", {
  attributes: {
    "ctx.payment.id": "pay_001",
    "ctx.payment.provider": "stripe",
    "ctx.payment.amount": 5000,
  },
});

await session.end();
```

### Mode C: Scoped Execution (Recommended)

All events inside `run()` automatically inherit session context via AsyncLocalStorage.

```typescript
// api/invoice/create.ts
export async function createInvoice(orgId: string, userId: string) {
  return telemetry.session()
    .actor("user", userId)
    .scope("organization", orgId)
    .run(async () => {
      // All emit() calls here automatically carry the session context
      telemetry.emit("igniter.billing.invoice.created", {
        attributes: {
          "ctx.invoice.id": "inv_101",
          "ctx.invoice.amount": 7500,
          "ctx.invoice.currency": "usd",
        },
      });

      // ... business logic ...

      telemetry.emit("igniter.billing.payment.succeeded", {
        attributes: {
          "ctx.payment.id": "pay_101",
          "ctx.payment.provider": "stripe",
          "ctx.payment.amount": 7500,
        },
      });
    });
}
```

***

## Step 4 — Graceful Shutdown

Call `shutdown()` before your process exits to flush pending events and clean up transports.

```typescript
// server.ts
import { telemetry } from "./telemetry/instance";

process.on("SIGTERM", async () => {
  console.log("Shutting down...");
  await telemetry.shutdown();
  process.exit(0);
});

process.on("SIGINT", async () => {
  console.log("Interrupted...");
  await telemetry.shutdown();
  process.exit(0);
});
```

<Callout type="warn">
  **Always call `shutdown()`** before the process exits. Transports like HTTP may have pending requests, and the Store adapter needs to close Redis connections. Without shutdown, you risk losing buffered events.
</Callout>

***

## Complete Example: Express Middleware

Putting it all together — an Express app with session correlation per request:

```typescript
// app.ts
import express from "express";
import { telemetry } from "./telemetry/instance";

const app = express();

// Middleware: wrap every request in a telemetry session
app.use((req, res, next) => {
  telemetry.session()
    .actor("user", req.headers["x-user-id"] as string ?? "anonymous")
    .scope("organization", req.headers["x-org-id"] as string ?? "unknown")
    .attributes({
      "ctx.request.method": req.method,
      "ctx.request.path": req.path,
      "ctx.request.ip": req.ip,
    })
    .run(async () => {
      telemetry.emit("request.started", {
        attributes: { "ctx.request.path": req.path },
      });

      res.on("finish", () => {
        telemetry.emit("request.completed", {
          attributes: { "ctx.request.status": res.statusCode },
        });
      });

      next();
    });
});

app.get("/api/invoices/:id", async (req, res) => {
  // Events here automatically have user + org context
  telemetry.emit("igniter.billing.invoice.created", {
    attributes: {
      "ctx.invoice.id": req.params.id,
      "ctx.invoice.amount": 2500,
      "ctx.invoice.currency": "usd",
    },
  });

  res.json({ status: "ok" });
});

app.listen(3000, () => {
  telemetry.emit("service.booted", {
    attributes: { "ctx.service.port": 3000 },
  });
});
```

**✅ Success!** You now have a production-ready telemetry setup with typed events, two transports, sampling, redaction, session correlation, and graceful shutdown.

***

## Next Steps

* [Defining Events](/docs/telemetry/defining-events) — Deep dive into event registries, namespaces, and groups
* [Builder Configuration](/docs/telemetry/builder-config) — All builder methods with parameter tables
* [Emitting Events](/docs/telemetry/emitting-events) — Attributes, levels, errors, and source metadata
* [Sessions](/docs/telemetry/sessions) — Session lifecycle and scoped execution patterns
* [Adapters](/docs/telemetry/adapters) — All 10 transport adapters


---

# Overview

> Type-safe, session-aware telemetry for Node.js applications. Typed event registries, automatic context correlation, PII redaction, sampling, and pluggable transport adapters.
URL: https://igniterjs.com/docs/telemetry

## Overview

`@igniter-js/telemetry` is a **type-safe, privacy-first telemetry backbone** for TypeScript applications. It unifies logs, events, and error reporting under a structured, correlated model — with typed event registries, automatic session context, PII redaction, sampling, and pluggable transports.

Whether you need to instrument a REST API, a background worker, or a Next.js app, telemetry gives you a single, governed pipeline for all observability data.

<Callout type="info">
  Telemetry is a **fully independent package**. Use it in any Node.js or Bun application — Express, Next.js, Fastify, Hono, or a background worker. No framework lock-in.
</Callout>

### Key Features

* **Type-safe events** — Define event schemas with Zod, get autocompletion on `emit()` calls, catch invalid events at compile time
* **Session correlation** — AsyncLocalStorage-based sessions automatically correlate events across async boundaries without manual context passing
* **PII protection** — Redact sensitive keys, hash PII fields, and truncate values before events leave the application
* **Volume control** — Per-level sampling rates, always/never patterns, and event filtering to control costs
* **Pluggable transports** — 10 built-in adapters (Logger, HTTP, OTLP, Sentry, Slack, Discord, Telegram, Memory, Mock, Store) — or build your own
* **Three emit modes** — Direct emit, manual session handles, and scoped execution (`session.run()`) — choose the right DX for each scenario
* **Event groups** — Nest events into namespaced groups for logical organization and discoverable autocompletion
* **Validation modes** — Validate events in development, production, or never — configurable per registry or globally
* **Predictable errors** — 22 stable error codes (`TELEMETRY_TRANSPORT_FAILED`, `TELEMETRY_SESSION_ENDED`) for programmatic handling

***

## Architecture

Telemetry follows a **builder → manager → transport fan-out** pipeline. Events flow through sampling, envelope construction, redaction, and then fan out to all registered transports.

```
┌──────────────────────────────────────────────────────────┐
│                       Your App                           │
├──────────────────────────────────────────────────────────┤
│ telemetry.emit('payment.succeeded', { attributes: ... }) │
└───────────────┬──────────────────────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────────────────────┐
│          IgniterTelemetryManager (runtime)               │
│  Session check → Sampling → Envelope → Redaction          │
└───────────────┬──────────────────────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────────────────────┐
│                     Transport Fan-out                    │
│  Logger | HTTP | OTLP | Sentry | Slack | Discord | Store  │
└──────────────────────────────────────────────────────────┘
```

Every event passes through: **resolve session → apply sampling → build envelope → apply redaction → fan-out to transports**.

### Mental Model

| Concept               | What it is                                | Example                                                                  |
| --------------------- | ----------------------------------------- | ------------------------------------------------------------------------ |
| **Builder**           | Fluent config chain (immutable)           | `IgniterTelemetry.create().withService('api').addTransport(...).build()` |
| **Manager**           | Runtime emitter with session support      | `telemetry.emit('user.login', { ... })`                                  |
| **Events Registry**   | Typed event definitions with Zod schemas  | `IgniterTelemetryEvents.namespace('igniter.jobs').event(...).build()`    |
| **Session**           | AsyncLocalStorage context for correlation | `telemetry.session().actor('user', 'usr_123').run(...)`                  |
| **Transport Adapter** | Pluggable destination for events          | `LoggerTransportAdapter.create({ logger: console })`                     |
| **Envelope**          | Normalized event payload with context     | `{ name, time, level, service, actor, scope, attributes }`               |

***

## Quick Start

Get telemetry running with a console transport in under 60 seconds.

<Steps>
  <Step>
    ### Install

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        npm install @igniter-js/telemetry
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @igniter-js/telemetry
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @igniter-js/telemetry
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @igniter-js/telemetry
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Create Telemetry Instance

    ```typescript
    import { IgniterTelemetry } from "@igniter-js/telemetry";
    import { LoggerTransportAdapter } from "@igniter-js/telemetry/adapters";

    const telemetry = IgniterTelemetry.create()
      .withService("billing-api")
      .withEnvironment(process.env.NODE_ENV ?? "development")
      .addTransport(LoggerTransportAdapter.create({ logger: console }))
      .build();
    ```
  </Step>

  <Step>
    ### Emit Events

    ```typescript
    // Direct emit — no session required
    telemetry.emit("service.booted", {
      attributes: { "ctx.service.uptime_ms": 42 },
    });

    telemetry.emit("payment.succeeded", {
      level: "info",
      attributes: {
        "ctx.payment.id": "pay_789",
        "ctx.payment.amount": 2999,
        "ctx.payment.currency": "usd",
      },
    });
    ```
  </Step>
</Steps>

**✅ Success!** You now have structured telemetry with a console transport.

***

## Three Emit Modes

Telemetry supports three distinct patterns for emitting events — choose the right one for your context.

### Mode A: Direct Emit

Simplest form. No session required. Each event stands alone.

```typescript
telemetry.emit("user.login", {
  attributes: { "ctx.user.id": "usr_123" },
});
```

### Mode B: Manual Session Handle

Create a session, bind actor/scope, emit events, then end it.

```typescript
const session = telemetry.session()
  .actor("user", "usr_123", { role: "admin" })
  .scope("organization", "org_456", { plan: "enterprise" });

session.emit("user.action", {
  attributes: { "ctx.action.type": "export" },
});

await session.end();
```

### Mode C: Scoped Execution (Recommended)

All events inside `run()` automatically inherit the session context — no manual context passing.

```typescript
await telemetry.session()
  .actor("user", "usr_123")
  .scope("organization", "org_456")
  .run(async () => {
    telemetry.emit("request.started", {
      attributes: { "ctx.request.path": "/api/orders" },
    });

    // ... your business logic ...

    telemetry.emit("request.completed", {
      attributes: { "ctx.request.status": 200 },
    });
  });
```

<Callout type="info">
  **Mode C is the recommended approach** for HTTP request handlers. It uses Node.js `AsyncLocalStorage` to automatically attach session context to all `emit()` calls within the callback — even across `await` boundaries.
</Callout>

***

## Next Steps

* [Installation](/docs/telemetry/installation) — All package managers and peer dependencies
* [Getting Started](/docs/telemetry/getting-started) — Complete walkthrough with typed events
* [Defining Events](/docs/telemetry/defining-events) — Typed event registries with Zod schemas
* [Builder Configuration](/docs/telemetry/builder-config) — All builder methods and options
* [Emitting Events](/docs/telemetry/emitting-events) — Attributes, levels, errors, and source metadata


---

# Installation

> Install @igniter-js/telemetry via npm, pnpm, yarn, or bun. Set up environment variables, TypeScript configuration, and understand peer dependencies.
URL: https://igniterjs.com/docs/telemetry/installation

## Installation

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/telemetry
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/telemetry
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/telemetry
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/telemetry
    ```
  </Tab>
</Tabs>

***

## Peer Dependencies

Telemetry depends on `@igniter-js/common` for the error system and logger interface. This is installed automatically by most package managers.

```json
{
  "peerDependencies": {
    "@igniter-js/common": "*"
  }
}
```

### Optional Dependencies

Some adapters have additional requirements:

| Adapter              | Peer Dependency     | Install                         |
| -------------------- | ------------------- | ------------------------------- |
| Sentry               | `@sentry/node`      | `npm install @sentry/node`      |
| Store                | `@igniter-js/store` | `npm install @igniter-js/store` |
| Events (Zod schemas) | `zod`               | `npm install zod`               |

***

## Environment Variables

Telemetry requires no environment variables by default. However, these are commonly configured:

```bash
# Service identification
NODE_ENV=production
APP_VERSION=1.4.2

# Transport-specific
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
TELEGRAM_BOT_TOKEN=123456:ABC-DEF
SENTRY_DSN=https://...@sentry.io/...
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
TELEMETRY_HTTP_URL=https://webhook.example.com/telemetry
TELEMETRY_HTTP_TOKEN=secret-token
```

***

## TypeScript Configuration

Telemetry is written in TypeScript and ships with full type declarations. No additional configuration is needed.

Your `tsconfig.json` should target at least:

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true
  }
}
```

<Callout type="info">
  Telemetry uses `AsyncLocalStorage` from `node:async_hooks`, which requires Node.js 16.4+. The package is tested on Node.js 22+.
</Callout>

***

## Subpath Exports

Telemetry supports subpath imports for tree-shakeable adapters:

```typescript
// Main entry — builder, manager, session, events, types, errors
import { IgniterTelemetry } from "@igniter-js/telemetry";

// Adapters subpath — all transport adapters
import { LoggerTransportAdapter } from "@igniter-js/telemetry/adapters";
```

***

## Minimal Setup

The absolute minimum to get telemetry working:

```typescript
import { IgniterTelemetry } from "@igniter-js/telemetry";
import { LoggerTransportAdapter } from "@igniter-js/telemetry/adapters";

const telemetry = IgniterTelemetry.create()
  .withService("my-app")
  .addTransport(LoggerTransportAdapter.create({ logger: console }))
  .build();

telemetry.emit("app.started");
```

**✅ Ready.** You can now emit structured telemetry events from anywhere in your application.

***

## Next Steps

* [Getting Started](/docs/telemetry/getting-started) — Build a complete telemetry setup with typed events
* [Defining Events](/docs/telemetry/defining-events) — Create typed event registries with Zod schemas
* [Builder Configuration](/docs/telemetry/builder-config) — Explore all builder options


---

# Sampling & Redaction

> Control telemetry volume with per-level sampling rates and glob patterns. Protect PII with key denylists, SHA-256 hashing, and string truncation — all applied before events leave the application.
URL: https://igniterjs.com/docs/telemetry/sampling-redaction

## Sampling & Redaction

Two critical policies that govern what data reaches your transports:

* **Sampling** — Controls *volume*. Which events are sent, and at what rate.
* **Redaction** — Controls *privacy*. Which data is removed or hashed before leaving your application.

Both are configured via the builder and applied during the emit pipeline: **Sampling → Envelope → Redaction → Transport fan-out**.

***

## Sampling

Sampling determines whether an event is forwarded to transports based on its level and name. It's the primary lever for controlling telemetry costs.

### Default Sampling Policy

```typescript
const DEFAULTS = {
  debugRate: 0.01,   // 1% of debug events
  infoRate: 0.1,     // 10% of info events
  warnRate: 1.0,     // 100% of warn events
  errorRate: 1.0,    // 100% of error events
  always: [],        // No forced sampling
  never: [],         // No forced drops
};
```

### Configuration

```typescript
const telemetry = IgniterTelemetry.create()
  .withSampling({
    debugRate: 0.01,        // 1% of debug events sampled
    infoRate: 0.1,          // 10% of info events sampled
    warnRate: 1.0,          // 100% of warn events
    errorRate: 1.0,         // 100% of error events
    always: [               // Always sampled (ignores rates)
      "*.failed",
      "*.error",
      "security.*",
      "audit.*",
    ],
    never: [                // Never sampled (always dropped)
      "health.check",
      "metrics.heartbeat",
      "debug.poll",
    ],
  })
  .addTransport(loggerAdapter)
  .build();
```

### How It Works

1. On every `emit()`, the sampler checks the event's **level** and **name**
2. If the name matches a `never` pattern → dropped immediately
3. If the name matches an `always` pattern → sent immediately
4. Otherwise → random sampling based on the level's rate

```typescript
// Example flow:
telemetry.emit("health.check", { ... });          // ❌ Dropped (never)
telemetry.emit("payment.failed", { level: "error" }); // ✅ Sent (always)
telemetry.emit("user.login", { level: "info" });  // 🎲 10% chance (infoRate)
telemetry.emit("cache.miss", { level: "debug" }); // 🎲 1% chance (debugRate)
```

### Glob Patterns

The `always` and `never` arrays support simple glob patterns with the `*` wildcard:

| Pattern        | Matches                                                                   |
| -------------- | ------------------------------------------------------------------------- |
| `*.failed`     | `payment.failed`, `order.failed`, `auth.failed`                           |
| `*.error`      | `db.error`, `api.error`                                                   |
| `security.*`   | `security.breach`, `security.login.brute_force`, `security.token.revoked` |
| `audit.*`      | `audit.user.deleted`, `audit.config.changed`                              |
| `health.check` | Only exact match `health.check`                                           |

### Recommended Policies

**Development** (log everything):

```typescript
sampling: {
  debugRate: 1.0,
  infoRate: 1.0,
  warnRate: 1.0,
  errorRate: 1.0,
}
```

**Production** (cost-conscious, all errors):

```typescript
sampling: {
  debugRate: 0.0,        // Never sample debug
  infoRate: 0.05,        // 5% of info
  warnRate: 1.0,         // All warnings
  errorRate: 1.0,        // All errors
  always: ["security.*", "audit.*"],
  never: ["health.check"],
}
```

**High-Volume Service** (aggressive sampling):

```typescript
sampling: {
  debugRate: 0.0,
  infoRate: 0.01,         // 1% of info
  warnRate: 0.5,          // 50% of warnings
  errorRate: 1.0,         // All errors
  always: ["*.error", "security.*"],
  never: ["health.check", "metrics.*", "debug.*"],
}
```

***

## Redaction

Redaction is applied **after sampling, before transport fan-out**. It modifies the event envelope's attributes in-memory — original data is never restored.

### Default Redaction Policy

```typescript
const DEFAULTS = {
  denylistKeys: [],    // Nothing removed by default
  hashKeys: [],         // Nothing hashed by default
  maxStringLength: 5000, // Strings longer than 5K truncated
};
```

### Configuration

```typescript
const telemetry = IgniterTelemetry.create()
  .withRedaction({
    denylistKeys: ["password", "token", "secret", "authorization", "cookie"],
    hashKeys: ["email", "ip", "userAgent", "phone", "ssn"],
    maxStringLength: 5000,
  })
  .addTransport(loggerAdapter)
  .build();
```

### How It Works

1. **Denylist**: Keys matching any denylist entry are **removed** from attributes
2. **Hash**: Keys matching any hash entry are **SHA-256 hashed** (preserving uniqueness for correlation)
3. **Truncation**: String values exceeding `maxStringLength` are truncated with `...[truncated]`

```typescript
// Before redaction:
telemetry.emit("user.login", {
  attributes: {
    "ctx.user.id": "usr_123",
    "ctx.user.email": "alice@example.com",   // Will be hashed
    "ctx.user.ip": "192.168.1.100",          // Will be hashed
    "ctx.auth.token": "sk_live_abc123...",   // Will be removed
    "ctx.auth.password": "s3cret!",           // Will be removed
    "ctx.request.body": "a".repeat(6000),     // Will be truncated
  },
});

// After redaction (what reaches transports):
{
  "ctx.user.id": "usr_123",                  // Untouched
  "ctx.user.email": "sha256:abc123def456...", // Hashed
  "ctx.user.ip": "sha256:789ghi012jkl...",   // Hashed
  // "ctx.auth.token" — REMOVED
  // "ctx.auth.password" — REMOVED
  "ctx.request.body": "aaaa...aaaa[truncated]", // Truncated at 5000 chars
}
```

<Callout type="warn">
  **Redaction is case-insensitive.** `password`, `Password`, and `PASSWORD` are all matched. Redaction only applies to `attributes` — envelope metadata (actor type, scope type, etc.) is not redacted.
</Callout>

### Denylist vs Hash

| Strategy | Effect                                | Use For                                      |
| -------- | ------------------------------------- | -------------------------------------------- |
| Denylist | Completely removes the key-value pair | Secrets, tokens, PII that must not be stored |
| Hash     | Replaces value with SHA-256 hash      | PII needed for correlation but not readable  |

```typescript
// Denylist — values that should NEVER leave the system
denylistKeys: [
  "password",
  "secret",
  "token",
  "authorization",
  "apiKey",
  "cookie",
  "jwt",
]

// Hash — PII needed for correlation but not in plain text
hashKeys: [
  "email",
  "ip",
  "userAgent",
  "phone",
  "ssn",
  "userId",
]
```

### Recommended Policies

**Basic** (catch common leaks):

```typescript
redaction: {
  denylistKeys: ["password", "token", "secret", "authorization"],
  hashKeys: ["email", "ip"],
}
```

**Strict** (GDPR/HIPAA compliance):

```typescript
redaction: {
  denylistKeys: [
    "password", "secret", "token", "authorization", "cookie",
    "creditCard", "ssn", "passport", "driverLicense",
  ],
  hashKeys: ["email", "ip", "userAgent", "phone", "name", "address"],
  maxStringLength: 1000, // Aggressive truncation
}
```

***

## Attribute Key Naming

To make redaction reliable, follow consistent naming:

```typescript
// ✅ Good — predictable keys for redaction
"ctx.user.email"
"ctx.user.ip"
"ctx.auth.token"
"ctx.payment.credit_card"

// ❌ Bad — unpredictable keys that bypass redaction
"email"           // Too generic
"user_email"      // Different convention
"userEmail"       // Different casing
"token"           // Could collide with non-sensitive "token"
```

<Callout type="info">
  Use the `ctx.*` naming convention consistently. This makes redaction rules predictable and prevents sensitive data from slipping through due to naming inconsistencies.
</Callout>

***

## Next Steps

* [Validation](/docs/telemetry/validation) — Event validation modes and strict mode
* [Best Practices](/docs/telemetry/best-practices) — Do's and Don'ts for production
* [Troubleshooting](/docs/telemetry/troubleshooting) — Common errors and solutions


---

# Sessions

> Master telemetry sessions — actor/scope binding, scoped execution with AsyncLocalStorage, session lifecycle, and real-world patterns for HTTP request handlers and background jobs.
URL: https://igniterjs.com/docs/telemetry/sessions

## Sessions

Sessions are the **context correlation engine** of telemetry. They bind actor, scope, and attributes to events — automatically propagating context across async boundaries using Node.js `AsyncLocalStorage`.

***

## Why Sessions?

Without sessions, you must manually pass user, tenant, and request context to every `emit()` call. With sessions, you set context once and all subsequent events inherit it:

```typescript
// ❌ Without sessions — repetitive context passing
telemetry.emit("step.one", {
  actor: { type: "user", id: "usr_123" },
  scope: { type: "organization", id: "org_456" },
  attributes: { "ctx.request.id": "req_abc" },
});
telemetry.emit("step.two", {
  actor: { type: "user", id: "usr_123" },  // Repeated!
  scope: { type: "organization", id: "org_456" },  // Repeated!
  attributes: { "ctx.request.id": "req_abc" },  // Repeated!
});

// ✅ With sessions — set once, inherited everywhere
await telemetry.session()
  .actor("user", "usr_123")
  .scope("organization", "org_456")
  .attributes({ "ctx.request.id": "req_abc" })
  .run(async () => {
    telemetry.emit("step.one", {});   // Context auto-inherited
    telemetry.emit("step.two", {});   // Context auto-inherited
  });
```

***

## Session Methods

| Method                     | Description                                     |
| -------------------------- | ----------------------------------------------- |
| `.actor(type, id?, tags?)` | Set the actor (who is acting)                   |
| `.scope(type, id, tags?)`  | Set the scope (what context)                    |
| `.attributes(attrs)`       | Merge session-level attributes                  |
| `.id(sessionId)`           | Set a custom session ID                         |
| `.emit(name, input?)`      | Emit an event with session context              |
| `.run(fn)`                 | Execute function with session as active context |
| `.end()`                   | End the session (no more modifications)         |
| `.getState()`              | Get a copy of current session state             |

***

## Session Mode A: Manual Handle

Create, configure, emit, and end manually. Best for short-lived, explicit sessions.

```typescript
async function handleWebhook(payload: { orgId: string; userId: string }) {
  const session = telemetry.session()
    .actor("system", "webhook", { source: "stripe" })
    .scope("organization", payload.orgId)
    .attributes({ "ctx.webhook.type": "payment_intent" });

  session.emit("webhook.received", {
    attributes: { "ctx.webhook.id": payload.userId },
  });

  try {
    await processWebhook(payload);
    session.emit("webhook.processed", {
      attributes: { "ctx.webhook.status": "success" },
    });
  } catch (error) {
    session.emit("webhook.failed", {
      level: "error",
      error: {
        name: error instanceof Error ? error.name : "Error",
        message: error instanceof Error ? error.message : String(error),
      },
    });
  }

  await session.end();
}
```

***

## Session Mode B: Scoped Execution

Wrap logic in `session.run()` for automatic context propagation. All `telemetry.emit()` calls inside the callback inherit the session.

```typescript
async function handleRequest(req: Request, res: Response) {
  await telemetry.session()
    .actor("user", req.headers["x-user-id"] as string)
    .scope("organization", req.headers["x-org-id"] as string)
    .attributes({
      "ctx.request.method": req.method,
      "ctx.request.path": req.url,
    })
    .run(async () => {
      // All emit calls here inherit user + org context
      telemetry.emit("request.started");

      const result = await processRequest(req);

      telemetry.emit("request.completed", {
        attributes: { "ctx.request.status": res.statusCode },
      });

      return result;
    });
}
```

<Callout type="info">
  **How it works:** `session.run()` enters an `AsyncLocalStorage` context. The telemetry manager checks for an active session on every `emit()` call. If found, session fields (actor, scope, attributes) are merged into the event envelope.
</Callout>

***

## Session Mode C: Nested Sessions

Sessions can be nested — inner sessions override outer session fields:

```typescript
await telemetry.session()
  .actor("system", "batch-job")
  .scope("organization", "org_global")
  .run(async () => {
    // All events here have: actor=system, scope=org_global

    telemetry.emit("batch.started");

    for (const org of organizations) {
      // Inner session overrides the scope
      await telemetry.session()
        .scope("organization", org.id)
        .run(async () => {
          // Events here: actor=system (inherited), scope=org_X (overridden)
          telemetry.emit("batch.org_processed", {
            attributes: { "ctx.org.id": org.id },
          });
        });
    }

    // Back to outer context: actor=system, scope=org_global
    telemetry.emit("batch.completed");
  });
```

***

## Session State

Get a copy of the current session state for inspection:

```typescript
const session = telemetry.session()
  .actor("user", "usr_123")
  .scope("organization", "org_456");

const state = session.getState();
console.log(state.sessionId);    // "sess_abc123..."
console.log(state.actor);        // { type: "user", id: "usr_123" }
console.log(state.scope);        // { type: "organization", id: "org_456" }
console.log(state.startedAt);    // "2024-01-15T10:30:00.000Z"
```

***

## Session Lifecycle

```
telemetry.session()   →  Create session
    .actor(...)       →  Configure actor
    .scope(...)       →  Configure scope
    .attributes(...)  →  Add shared attributes
    .run(async () => {   →  Enter scoped context
      telemetry.emit(...) →  Events inherit session
      telemetry.emit(...) →  Events inherit session
    })                →  Exit scoped context
session.end()         →  End session (or auto-ended after run())
```

### After End

Once ended, the session rejects further modifications:

```typescript
const session = telemetry.session().actor("user", "usr_123");
await session.end();

// ❌ Throws TELEMETRY_SESSION_ENDED
session.actor("user", "another_user");
```

***

## Static Method: `getActive()`

Check if there's an active session from anywhere in your code:

```typescript
import { IgniterTelemetrySession } from "@igniter-js/telemetry";

const activeSession = IgniterTelemetrySession.getActive();

if (activeSession) {
  console.log("Active session:", activeSession.sessionId);
  console.log("Actor:", activeSession.actor);
  console.log("Scope:", activeSession.scope);
}
```

***

## Real-World Example: Next.js Middleware

Wrap every API route in a telemetry session:

```typescript
// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { telemetry } from "@/lib/telemetry";

export async function middleware(request: NextRequest) {
  const userId = request.headers.get("x-user-id") ?? "anonymous";
  const orgId = request.headers.get("x-org-id") ?? "unknown";

  return telemetry.session()
    .actor("user", userId)
    .scope("organization", orgId)
    .attributes({
      "ctx.request.method": request.method,
      "ctx.request.path": request.nextUrl.pathname,
      "ctx.request.ip": request.ip ?? "unknown",
    })
    .run(async () => {
      telemetry.emit("request.started", {
        attributes: { "ctx.request.path": request.nextUrl.pathname },
      });

      const response = NextResponse.next();

      telemetry.emit("request.completed", {
        attributes: { "ctx.request.status": response.status },
      });

      return response;
    });
}

export const config = {
  matcher: "/api/:path*",
};
```

***

## Real-World Example: Express Middleware

```typescript
import express from "express";
import { telemetry } from "./telemetry";

const app = express();

app.use((req, res, next) => {
  telemetry.session()
    .actor("user", req.headers["x-user-id"] as string ?? "anonymous")
    .scope("organization", req.headers["x-org-id"] as string ?? "unknown")
    .attributes({
      "ctx.request.method": req.method,
      "ctx.request.path": req.path,
      "ctx.request.ip": req.ip,
    })
    .run(async () => {
      telemetry.emit("request.started", {
        attributes: { "ctx.request.path": req.path },
      });

      res.on("finish", () => {
        telemetry.emit("request.completed", {
          attributes: { "ctx.request.status": res.statusCode },
        });
      });

      next();
    });
});
```

***

## Next Steps

* [Emitting Events](/docs/telemetry/emitting-events) — Attributes, levels, errors, and source metadata
* [Adapters](/docs/telemetry/adapters) — Route events to different destinations
* [Framework Integration](/docs/telemetry/framework-integration) — Next.js, Express, and Fastify patterns


---

# Troubleshooting

> Diagnose and fix common telemetry issues — error codes, transport failures, session problems, event validation errors, and performance concerns.
URL: https://igniterjs.com/docs/telemetry/troubleshooting

## Troubleshooting

This guide covers the most common issues, their error codes, and step-by-step solutions.

***

## Error Code Reference

Telemetry uses 22 stable error codes. Use them for programmatic error handling.

### Configuration Errors

| Code                              | Cause                | Solution                                                  |
| --------------------------------- | -------------------- | --------------------------------------------------------- |
| `TELEMETRY_SERVICE_REQUIRED`      | Service name not set | Call `.withService("my-api")` before `.build()`           |
| `TELEMETRY_ENVIRONMENT_REQUIRED`  | Environment not set  | Call `.withEnvironment("production")` before `.build()`   |
| `TELEMETRY_CONFIGURATION_INVALID` | Invalid config state | Check all builder methods. Verify no conflicting options. |

### Transport Errors

| Code                              | Cause                                             | Solution                                                            |
| --------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
| `TELEMETRY_INVALID_TRANSPORT`     | Falsy transport passed to `.addTransport()`       | Pass a valid adapter instance                                       |
| `TELEMETRY_TRANSPORT_FAILED`      | All transports failed for an event                | Check transport configs (URLs, tokens). Check network connectivity. |
| `TELEMETRY_TRANSPORT_INIT_FAILED` | Transport failed during `.build()` initialization | Fix the failing transport or remove it                              |

### Event Errors

| Code                           | Cause                                      | Solution                                            |
| ------------------------------ | ------------------------------------------ | --------------------------------------------------- |
| `TELEMETRY_INVALID_EVENT_NAME` | Event name format is invalid               | Use dot-separated names: `"namespace.group.action"` |
| `TELEMETRY_UNKNOWN_EVENT`      | Emitting unregistered event in strict mode | Register the event or disable strict mode           |
| `TELEMETRY_DUPLICATE_EVENT`    | Event name already registered in namespace | Use unique event names within a namespace           |

### Schema & Validation Errors

| Code                                 | Cause                                   | Solution                                                         |
| ------------------------------------ | --------------------------------------- | ---------------------------------------------------------------- |
| `TELEMETRY_SCHEMA_VALIDATION_FAILED` | Event attributes don't match Zod schema | Check attribute names and types against registered schema        |
| `TELEMETRY_INVALID_NAMESPACE`        | Namespace format is invalid             | Use dot-separated names: `"igniter.feature"`                     |
| `TELEMETRY_RESERVED_NAMESPACE`       | Using a reserved namespace prefix       | Avoid `igniter.*` unless part of an Igniter.js integration       |
| `TELEMETRY_DUPLICATE_NAMESPACE`      | Same namespace registered twice         | Merge events into a single namespace or use different namespaces |

### Session Errors

| Code                        | Cause                                | Solution                       |
| --------------------------- | ------------------------------------ | ------------------------------ |
| `TELEMETRY_SESSION_ENDED`   | Modifying or emitting after `.end()` | Create a new session if needed |
| `TELEMETRY_SESSION_INVALID` | Session in invalid state             | Create a fresh session         |

### Scope & Actor Errors

| Code                        | Cause                      | Solution                    |
| --------------------------- | -------------------------- | --------------------------- |
| `TELEMETRY_DUPLICATE_SCOPE` | Same scope key added twice | Use unique scope keys       |
| `TELEMETRY_INVALID_SCOPE`   | Scope key is invalid       | Use alphanumeric scope keys |
| `TELEMETRY_DUPLICATE_ACTOR` | Same actor key added twice | Use unique actor keys       |
| `TELEMETRY_INVALID_ACTOR`   | Actor key is invalid       | Use alphanumeric actor keys |

### Emit & Runtime Errors

| Code                                | Cause                 | Solution                                              |
| ----------------------------------- | --------------------- | ----------------------------------------------------- |
| `TELEMETRY_EMIT_FAILED`             | Emit pipeline failed  | Check transports are healthy. Check event attributes. |
| `TELEMETRY_RUNTIME_NOT_INITIALIZED` | Manager not built yet | Call `.build()` before using the manager              |

***

## Common Issues

### 1. "No events are showing up in my transport"

**Symptom:** You call `telemetry.emit()` but nothing appears in logs/Sentry/Slack.

**Likely causes:**

* **Sampling is filtering events.** Check your sampling config — if `infoRate: 0.1`, only 10% of info events are sent.

```typescript
// Temporarily set all rates to 1.0 for debugging
.withSampling({ debugRate: 1.0, infoRate: 1.0, warnRate: 1.0, errorRate: 1.0 })
```

* **Event name matches a `never` pattern.** Check `never: ["health.check"]` — events with matching names are dropped.

* **Transport is filtering by level.** Check `minLevel` on Logger/Slack/Discord adapters.

```typescript
// Check: minLevel: "error" means debug/info/warn are dropped
LoggerTransportAdapter.create({ logger: console, minLevel: "debug" })
```

***

### 2. "TELEMETRY\_TRANSPORT\_FAILED — all transports failed"

**Symptom:** Events throw because every transport failed.

**Likely causes:**

* **Network issues.** HTTP/OTLP adapters can't reach their endpoints.
* **Invalid credentials.** Slack/Discord/Telegram webhook URLs are wrong or expired.
* **Missing peer dependency.** Sentry adapter needs `@sentry/node` installed.

**Solutions:**

1. Test each transport individually — remove all but one, verify it works
2. Check environment variables are set in the running process
3. Add a Logger transport as a fallback:

```typescript
.addTransport(LoggerTransportAdapter.create({ logger: console })) // Always works
.addTransport(HttpTransportAdapter.create({ url: "..." }))
```

***

### 3. "TELEMETRY\_DUPLICATE\_NAMESPACE — namespace already registered"

**Symptom:** Adding a second event descriptor with the same namespace throws.

**Fix:** Merge events into a single namespace:

```typescript
// ❌ Two separate registries with same namespace
const AuthLogin = IgniterTelemetryEvents
  .namespace("igniter.auth")
  .event("login.succeeded", schema)
  .build();

const AuthLogout = IgniterTelemetryEvents
  .namespace("igniter.auth")    // DUPLICATE!
  .event("logout", schema)
  .build();

// ✅ Single registry with all events
const AuthEvents = IgniterTelemetryEvents
  .namespace("igniter.auth")
  .event("login.succeeded", schema)
  .event("logout", schema)
  .build();
```

***

### 4. "TELEMETRY\_SCHEMA\_VALIDATION\_FAILED — event validation failed"

**Symptom:** Emitting typed events throws schema validation errors.

**Likely causes:**

* **Missing required attributes.** Check your Zod schema for required fields.
* **Wrong attribute types.** Schema expects `z.number()` but you passed a string.
* **Attribute key mismatch.** Schema uses `"ctx.order.id"` but you emitted `"orderId"`.

**Fix:**

```typescript
// Check the schema definition
const schema = z.object({
  "ctx.order.id": z.string(),        // Required, string
  "ctx.order.total": z.number(),     // Required, number
  "ctx.order.currency": z.string().length(3).optional(), // Optional
});

// Match your emit exactly:
telemetry.emit("igniter.orders.completed", {
  attributes: {
    "ctx.order.id": "ord_123",       // ✅ string
    "ctx.order.total": 2999,         // ✅ number (not "2999")
    "ctx.order.currency": "usd",     // ✅ optional, 3 chars
  },
});
```

***

### 5. "TELEMETRY\_SESSION\_ENDED — cannot modify session"

**Symptom:** Trying to call `.actor()`, `.scope()`, or `.emit()` on an ended session.

**Fix:** Sessions are single-use. Create a new one:

```typescript
// ❌ Reusing an ended session
const session = telemetry.session().actor("user", "usr_123");
await session.end();
session.emit("event", {});  // Throws!

// ✅ Create a new session
const newSession = telemetry.session().actor("user", "usr_123");
newSession.emit("event", {});
await newSession.end();
```

***

### 6 "Redaction isn't working — sensitive data still visible"

**Symptom:** You configured denylistKeys but passwords still appear in logs.

**Likely causes:**

* **Case mismatch.** Redaction is case-insensitive — but your key might use a different convention.
* **Nested keys not matched.** Redaction matches top-level attribute keys only. If your attribute value is an object containing a sensitive field, it won't be redacted.

```typescript
// ✅ Works — top-level key matched
attributes: {
  "ctx.auth.password": "s3cret!"   // Removed!
}

// ❌ Doesn't work — password is nested inside an object value
attributes: {
  "ctx.auth": {
    password: "s3cret!"            // NOT removed — it's inside an object
  }
}
```

**Fix:** Always flatten sensitive data to top-level attribute keys:

```typescript
// ✅ Flatten sensitive fields
attributes: {
  "ctx.auth.method": "password",
  "ctx.auth.password": "s3cret!",   // Will be redacted
}
```

***

### 7. "Telemetry is slowing down my application"

**Symptom:** High latency or throughput drops when telemetry is enabled.

**Likely causes:**

* **Too many transports.** Each transport processes every event.
* **Sync operations in transport.** Custom adapters with blocking code.
* **No sampling in production.** All debug/info events being processed.

**Solutions:**

1. Enable aggressive sampling in production (see [Sampling & Redaction](/docs/telemetry/sampling-redaction))
2. Reduce transport count to essentials
3. Use `minLevel` to filter noisy transports
4. Ensure custom transport `handle()` is async and non-blocking

***

## Debugging Checklist

When something isn't working, run through this checklist:

1. **Is `.build()` called?** The manager is only created after `.build()`.
2. **Is at least one transport added?** Without transports, events go nowhere.
3. **Are events being sampled out?** Set all rates to 1.0 temporarily.
4. **Is strict mode hiding errors?** Set `strict: false` to log instead of throw.
5. **Are environment variables set?** Check `process.env` for transport credentials.
6. **Is the logger configured?** Add `.withLogger(...)` to see internal telemetry logs.
7. **Is `shutdown()` called on exit?** Buffered events may be lost without it.

***

## Next Steps

* [API Reference](/docs/telemetry/api-reference) — Complete API documentation
* [Best Practices](/docs/telemetry/best-practices) — Production patterns
* [Framework Integration](/docs/telemetry/framework-integration) — Next.js, Express, Fastify


---

# Event Validation

> Validate telemetry events against Zod schemas — choose between development-only, always-on, or no validation. Configure strict mode, per-registry options, and understand the validation pipeline.
URL: https://igniterjs.com/docs/telemetry/validation

## Event Validation

Validation ensures that emitted events match their registered Zod schemas. It catches typos, missing fields, and wrong types — before events reach your transports.

<Callout type="info">
  Validation is **only applied when typed events are registered** via `.addEvents()`. Untyped events (plain string names) are never validated.
</Callout>

***

## Validation Modes

Three modes control when validation runs:

| Mode            | Behavior                                       | Use Case                                                 |
| --------------- | ---------------------------------------------- | -------------------------------------------------------- |
| `"development"` | Validate only when `NODE_ENV !== "production"` | Catch schema errors in dev, skip in prod for performance |
| `"always"`      | Validate on every emit, including production   | Strict schemas must never be violated                    |
| `"none"`        | Never validate                                 | Untyped events or legacy code                            |

### Setting Validation Mode

**Per-registry** (recommended for granular control):

```typescript
const telemetry = IgniterTelemetry.create()
  .addEvents(BillingEvents, { mode: "always", strict: true })
  .addEvents(DebugEvents, { mode: "development" })
  .addEvents(LegacyEvents, { mode: "none" })
  .addTransport(loggerAdapter)
  .build();
```

**Global** (applies to all registries as default):

```typescript
const telemetry = IgniterTelemetry.create()
  .withValidation({ mode: "always", strict: true })
  .addEvents(BillingEvents)   // Inherits global: always + strict
  .addTransport(loggerAdapter)
  .build();
```

Per-registry options override global options for that specific registry.

***

## Strict Mode

When `strict: true`, emitting an event name that isn't in any registered namespace throws `TELEMETRY_UNKNOWN_EVENT`:

```typescript
const telemetry = IgniterTelemetry.create()
  .addEvents(BillingEvents, { mode: "always", strict: true })
  .addTransport(loggerAdapter)
  .build();

// ❌ Throws TELEMETRY_UNKNOWN_EVENT — event not in BillingEvents
telemetry.emit("unknown.event", { attributes: {} });
```

When `strict: false` (default), unknown events are logged as warnings but not thrown:

```typescript
const telemetry = IgniterTelemetry.create()
  .addEvents(BillingEvents, { mode: "development", strict: false })
  .addTransport(loggerAdapter)
  .build();

// ⚠️ Logs a warning but does not throw
telemetry.emit("unknown.event", { attributes: {} });
```

***

## Schema Validation

When an event name is recognized (belongs to a registered namespace), the event's attributes are validated against its Zod schema:

```typescript
import { z } from "zod";
import { IgniterTelemetryEvents } from "@igniter-js/telemetry";

const PaymentEvents = IgniterTelemetryEvents
  .namespace("igniter.payments")
  .event("succeeded", z.object({
    "ctx.payment.id": z.string(),
    "ctx.payment.amount": z.number(),
  }))
  .build();

const telemetry = IgniterTelemetry.create()
  .addEvents(PaymentEvents, { mode: "always" })
  .addTransport(loggerAdapter)
  .build();

// ✅ Passes validation
telemetry.emit("igniter.payments.succeeded", {
  attributes: {
    "ctx.payment.id": "pay_123",
    "ctx.payment.amount": 2999,
  },
});

// ❌ Fails validation — missing required field "ctx.payment.id"
telemetry.emit("igniter.payments.succeeded", {
  attributes: {
    "ctx.payment.amount": 2999,
  },
});
```

<Callout type="warn">
  Schema validation failures throw `TELEMETRY_SCHEMA_VALIDATION_FAILED` with details about which fields failed. In `"development"` mode, this only happens outside of production.
</Callout>

***

## Recommended Configuration

### Development

Catch everything early — validate all events, log unknown events:

```typescript
withValidation({ mode: "always", strict: false })
```

### Production

Skip validation for performance, but keep strict mode to catch truly unknown events:

```typescript
withValidation({ mode: "development", strict: true })
```

### CI/Testing

Always validate, always be strict:

```typescript
withValidation({ mode: "always", strict: true })
```

***

## Validation Pipeline

The validation pipeline runs during `emit()`:

```
emit('event.name', input)
  ↓
1. Check if event name exists in any registry? (strict check)
  ↓  (if strict && unknown) → throw TELEMETRY_UNKNOWN_EVENT
  ↓
2. Check validation mode (development | always | none)
  ↓  (if 'none') → skip validation, emit
  ↓  (if 'development' && NODE_ENV === 'production') → skip
  ↓
3. Look up schema for event name
  ↓
4. Validate input.attributes against schema
  ↓  (if invalid) → throw TELEMETRY_SCHEMA_VALIDATION_FAILED
  ↓
5. Emit event
```

***

## Performance Considerations

* **Development mode** has zero runtime cost in production — validation is skipped entirely
* **Always mode** adds Zod schema parsing overhead on every emit — use only for critical events
* **Strict mode** adds a registry lookup on every emit — negligible cost
* Untyped events (events without a registered namespace) **skip validation entirely** regardless of settings

***

## Next Steps

* [Best Practices](/docs/telemetry/best-practices) — Do's and Don'ts for production telemetry
* [Troubleshooting](/docs/telemetry/troubleshooting) — Common validation errors and solutions
* [Defining Events](/docs/telemetry/defining-events) — Create typed event registries


---

# Caching

> Improve performance with built-in in-memory and persistent caching. Reduce network calls, speed up your UI, and control cache invalidation.
URL: https://igniterjs.com/docs/caller/caching

Caller provides a layered caching system that works out of the box with in-memory storage and can be extended to persistent stores like Redis.

***

## How Caching Works

When you call `.stale(milliseconds)` on a request, Caller:

1. Checks if a cached response exists and is within the stale window
2. If **found and fresh** → returns cached data immediately (no network call)
3. If **not found or expired** → makes the network request → caches the result

```typescript
// First call — network request, cached for 30s
const { data: fresh } = await api.get('/users')
  .stale(30_000)
  .execute();

// Second call (within 30s) — instant cached response
const { data: cached } = await api.get('/users')
  .stale(30_000)
  .execute();
// No network request made!
```

***

## Basic Caching

The `.stale()` method accepts milliseconds. Simple and predictable:

```typescript
// Cache for 30 seconds
await api.get('/users').stale(30_000).execute();

// Cache for 5 minutes
await api.get('/config').stale(300_000).execute();

// Cache for 1 hour
await api.get('/constants').stale(3_600_000).execute();
```

### Cache Keys

By default, Caller generates cache keys from the request URL. Use `.cache()` to set a custom key:

```typescript
// Custom cache key for manual invalidation
await api.get('/me')
  .cache('default', 'current-user')
  .stale(60_000)
  .execute();

// Same data from a different endpoint can share the cache key
await api.get('/users/current')
  .cache('default', 'current-user')
  .stale(60_000)
  .execute();
```

### Fetch Cache Strategy

The first parameter to `.cache()` is the native `RequestCache` strategy:

| Strategy           | Behavior                                             |
| ------------------ | ---------------------------------------------------- |
| `'default'`        | Browser default cache behavior                       |
| `'no-store'`       | Never cache (bypasses both browser and Caller cache) |
| `'reload'`         | Fetch from network, update cache                     |
| `'force-cache'`    | Use cache even if stale                              |
| `'only-if-cached'` | Only return cached data, error otherwise             |

```typescript
// Force network fetch, bypassing browser cache
await api.get('/real-time-data')
  .cache('no-store')
  .execute();

// Prefer cache for static data
await api.get('/static-content')
  .cache('force-cache')
  .stale(600_000)
  .execute();
```

***

## Cache Invalidation

Invalidate cached entries when data changes (e.g., after a mutation):

### Programmatic Invalidation

Use the static `IgniterCallerManager` methods:

```typescript
import { IgniterCallerManager } from '@igniter-js/caller';

// After creating a user, invalidate the users list
const { error } = await api.post('/users').body(newUser).execute();

if (!error) {
  IgniterCallerManager.on('response', (result, context) => {
    // React to specific responses
    if (context.url.includes('/users') && context.method === 'POST') {
      // Clear cache for this resource
      console.log('User created — cache should be refreshed');
    }
  });
}
```

### React Hook Invalidation

In React, use the `.invalidate()` method from hooks:

```tsx
function CreateUserForm() {
  const main = useCaller('main');

  const handleSubmit = async (data: CreateUserInput) => {
    const { error } = await main.post('/users').body(data).execute();

    if (!error) {
      // Invalidate all cached queries for /users
      main.invalidate('/users');
    }
  };

  return <form onSubmit={handleSubmit}>...</form>;
}
```

***

## Persistent Caching (Redis / Store Adapter)

For server-side applications, use a persistent store to share cache across instances:

```typescript
import { IgniterCaller } from '@igniter-js/caller';

// Implement the StoreAdapter interface for your backend
class RedisStoreAdapter {
  readonly client: RedisClient;

  constructor(redisUrl: string) {
    this.client = createRedisClient(redisUrl);
  }

  async get<T>(key: string): Promise<T | null> {
    const raw = await this.client.get(key);
    return raw ? JSON.parse(raw) : null;
  }

  async set(key: string, value: any, options?: { ttl?: number }): Promise<void> {
    const serialized = JSON.stringify(value);
    if (options?.ttl) {
      await this.client.setex(key, options.ttl, serialized);
    } else {
      await this.client.set(key, serialized);
    }
  }

  async delete(key: string): Promise<void> {
    await this.client.del(key);
  }

  async has(key: string): Promise<boolean> {
    return (await this.client.exists(key)) === 1;
  }
}

// Use it
const redisStore = new RedisStoreAdapter(process.env.REDIS_URL!);

const api = IgniterCaller.create()
  .withBaseUrl('https://api.example.com')
  .withStore(redisStore, {
    ttl: 3600,                // 1 hour default TTL
    keyPrefix: 'api-cache:',  // Redis key prefix
    fallbackToFetch: true,    // Fall back to in-memory if Redis is down
  })
  .build();
```

### Store Options

| Option            | Default             | Description                                      |
| ----------------- | ------------------- | ------------------------------------------------ |
| `ttl`             | `3600`              | Default TTL in seconds                           |
| `keyPrefix`       | `'igniter:caller:'` | Prefix for all cache keys                        |
| `fallbackToFetch` | `true`              | Fall back to in-memory when store is unavailable |

***

## Testing with MockStoreAdapter

Use the built-in mock adapter for testing:

```typescript
import { MockCallerStoreAdapter } from '@igniter-js/caller/adapters';
import { IgniterCaller } from '@igniter-js/caller';

describe('Cache behavior', () => {
  it('uses store for caching', async () => {
    const store = MockCallerStoreAdapter.create();

    const api = IgniterCaller.create()
      .withStore(store)
      .build();

    // First call: cache miss
    await api.get('/data').stale(30_000).execute();

    // Second call: should hit cache
    await api.get('/data').stale(30_000).execute();

    // Assert
    expect(store.calls.set).toBe(1);
    expect(store.calls.get).toBeGreaterThanOrEqual(1);
  });
});
```

***

## Caching with Telemetry

Monitor cache performance with telemetry events:

```typescript
import { IgniterCallerTelemetryEvents } from '@igniter-js/caller/telemetry';

// Every cache hit emits: igniter.caller.cache.read.hit
// Every successful request emits: igniter.caller.request.execute.success (with ctx.cache.hit)
```

***

## Best Practices

<Callout type="success" title="Caching Guidelines">
  * **Cache GET requests** — mutations (POST/PUT/PATCH/DELETE) always bypass cache
  * **Use reasonable stale times** — 5-30s for dynamic data, 5-60min for static data
  * **Invalidate on mutation** — clear related caches when data changes
  * **Use custom keys** for data that doesn't map 1:1 to URLs
  * **Monitor hit rates** with telemetry to tune stale times
</Callout>

<Callout type="warn" title="Common Mistakes">
  * **Don't** cache user-specific data with shared keys — use user-specific cache keys
  * **Don't** set extremely long stale times for rapidly changing data
  * **Don't** forget that cache is in-memory by default — restarts clear it
  * **Don't** use `.stale()` without a store adapter if you need cross-instance caching
</Callout>

***

## Next Steps

<Cards>
  <Card title="Retries" description="Handle transient failures with automatic retry logic" href="/docs/caller/retries" />

  <Card title="Telemetry" description="Monitor cache hit rates and request performance" href="/docs/caller/telemetry" />

  <Card title="Real-World Examples" description="See caching patterns in production scenarios" href="/docs/caller/real-world-examples" />
</Cards>


---

# Interceptors

> Transform requests and responses globally with interceptors. Perfect for authentication, logging, error normalization, and request modification.
URL: https://igniterjs.com/docs/caller/interceptors

Interceptors allow you to run custom logic before a request is sent or after a response is received. They are the primary mechanism for cross-cutting concerns like authentication, logging, error normalization, and request enrichment.

***

## Request Interceptors

Request interceptors receive the current request configuration and return the modified configuration. They execute **in order** before every request.

```typescript
const api = IgniterCaller.create()
  .withBaseUrl('https://api.example.com')

  // Add auth token
  .withRequestInterceptor(async (config) => ({
    ...config,
    headers: {
      ...config.headers,
      'Authorization': `Bearer ${getAuthToken()}`,
    },
  }))

  // Add request tracing
  .withRequestInterceptor(async (config) => ({
    ...config,
    headers: {
      ...config.headers,
      'X-Request-ID': crypto.randomUUID(),
      'X-Timestamp': new Date().toISOString(),
    },
  }))

  .build();
```

### Signature

```typescript
type RequestInterceptor = (
  config: IgniterCallerRequestOptions,
) => IgniterCallerRequestOptions | Promise<IgniterCallerRequestOptions>;
```

***

## Response Interceptors

Response interceptors receive the response envelope and return a (possibly transformed) envelope. They execute **in order** after every response.

```typescript
const api = IgniterCaller.create()
  .withResponseInterceptor(async (response) => {
    // Log all responses
    console.log(`[${response.status}] ${response.headers?.get('x-request-id')}`);
    return response;
  })

  .withResponseInterceptor(async (response) => {
    // Normalize empty data
    if (response.data === '' || response.data === undefined) {
      return { ...response, data: null as any };
    }
    return response;
  })

  .build();
```

### Signature

```typescript
type ResponseInterceptor = <T>(
  response: IgniterCallerApiResponse<T>,
) => IgniterCallerApiResponse<T> | Promise<IgniterCallerApiResponse<T>>;
```

***

## Common Patterns

### Authentication Token Refresh

A complete auth interceptor that handles token refresh on 401 responses:

```typescript
let accessToken: string | null = null;
let refreshPromise: Promise<string> | null = null;

const api = IgniterCaller.create()
  .withBaseUrl('https://api.example.com')

  // Inject token
  .withRequestInterceptor(async (config) => {
    if (!accessToken) {
      accessToken = await refreshAccessToken();
    }
    return {
      ...config,
      headers: {
        ...config.headers,
        'Authorization': `Bearer ${accessToken}`,
      },
    };
  })

  // Handle 401 — clear token so next request refreshes
  .withResponseInterceptor(async (response) => {
    if (response.status === 401) {
      accessToken = null;
      // Optionally redirect to login
      if (typeof window !== 'undefined') {
        window.location.href = '/login';
      }
    }
    return response;
  })

  .build();

async function refreshAccessToken(): Promise<string> {
  if (!refreshPromise) {
    refreshPromise = fetch('/api/auth/refresh', { credentials: 'include' })
      .then(r => r.json())
      .then(data => data.accessToken)
      .finally(() => { refreshPromise = null; });
  }
  return refreshPromise;
}
```

### Request Logging Middleware

```typescript
const api = IgniterCaller.create()
  .withRequestInterceptor(async (config) => {
    const startTime = Date.now();

    // Store start time on the config for use in response interceptor
    (config as any)._startTime = startTime;

    console.log(`→ ${config.method} ${config.url}`);
    return config;
  })

  .withResponseInterceptor(async (response) => {
    const startTime = (response as any)._startTime as number;
    const duration = startTime ? Date.now() - startTime : undefined;

    const emoji = (response.status ?? 0) < 400 ? '✅' : '❌';
    const timing = duration ? ` (${duration}ms)` : '';
    console.log(`${emoji} ${response.status}${timing}`);

    return response;
  })

  .build();
```

### Error Normalization

```typescript
const api = IgniterCaller.create()
  .withResponseInterceptor(async (response) => {
    // Some APIs wrap errors differently — normalize them
    if (response.error && (response.error as any).details?.errors) {
      return {
        ...response,
        error: {
          ...response.error,
          message: formatValidationErrors((response.error as any).details.errors),
        },
      } as any;
    }

    // Convert 5xx errors to user-friendly messages in production
    if ((response.status ?? 0) >= 500 && process.env.NODE_ENV === 'production') {
      return {
        ...response,
        error: {
          ...response.error,
          message: 'An unexpected error occurred. Please try again.',
        },
      } as any;
    }

    return response;
  })

  .build();
```

### Conditional Headers

Add headers based on request characteristics:

```typescript
const api = IgniterCaller.create()
  .withRequestInterceptor(async (config) => {
    const headers: Record<string, string> = {};

    // Add idempotency key for mutating requests
    if (['POST', 'PUT', 'PATCH'].includes(config.method)) {
      headers['X-Idempotency-Key'] = crypto.randomUUID();
    }

    // Add version header for specific endpoints
    if (config.url?.startsWith('/v2/')) {
      headers['Accept-Version'] = '2.0';
    }

    return {
      ...config,
      headers: { ...config.headers, ...headers },
    };
  })

  .build();
```

### Request Deduplication

Prevent duplicate in-flight requests for the same URL:

```typescript
const inflightRequests = new Map<string, Promise<any>>();

const api = IgniterCaller.create()
  .withRequestInterceptor(async (config) => {
    const key = `${config.method}:${config.url}`;

    if (config.method === 'GET') {
      const existing = inflightRequests.get(key);
      if (existing) {
        // Return a marker — this doesn't actually deduplicate at the execute level
        // For true deduplication, use .stale() caching instead
      }
    }

    return config;
  })

  .build();
```

<Callout type="info" title="For request deduplication">
  Interceptors alone can't fully deduplicate requests. Use `.stale()` caching for automatic deduplication of identical GET requests within the stale window.
</Callout>

***

## Interceptor Execution Order

Interceptors execute in the order they're registered:

```
Request Interceptors (first → last)
     ↓
   Fetch
     ↓
Response Interceptors (first → last)
```

```typescript
const api = IgniterCaller.create()
  // Runs first: adds auth
  .withRequestInterceptor(authInterceptor)
  // Runs second: adds tracing
  .withRequestInterceptor(tracingInterceptor)
  .build();

// On response:
// tracingInterceptor response runs first
// authInterceptor response runs second
```

***

## Testing Interceptors

```typescript
import { describe, it, expect, vi } from 'vitest';

describe('Auth Interceptor', () => {
  it('adds authorization header to every request', async () => {
    const interceptor = vi.fn(async (config) => ({
      ...config,
      headers: { ...config.headers, 'Authorization': 'Bearer test-token' },
    }));

    const api = IgniterCaller.create()
      .withRequestInterceptor(interceptor)
      .build();

    // Interceptor runs on execute
    await api.get('/test').execute();
    expect(interceptor).toHaveBeenCalledTimes(1);
  });

  it('normalizes empty responses', async () => {
    const interceptor = async (response: any) => {
      if (response.data === '') {
        return { ...response, data: null };
      }
      return response;
    };

    const result = await interceptor({ data: '', status: 200, headers: new Headers() });
    expect(result.data).toBeNull();
  });
});
```

***

## Best Practices

<Callout type="success" title="Interceptor Guidelines">
  * **Keep interceptors focused** — each interceptor should do one thing well
  * **Register in order** — auth first, then tracing, then domain-specific logic
  * **Always return the config/response** — don't accidentally drop the object
  * **Handle errors gracefully** — a failing interceptor shouldn't break all requests
  * **Test interceptors in isolation** — they're pure functions, easy to unit test
</Callout>

<Callout type="warn" title="Common Pitfalls">
  * **Don't** forget to `await` async operations — hanging promises break the request chain
  * **Don't** mutate the config object — always spread and return a new object
  * **Don't** use interceptors for data fetching — use the request builder's `.execute()` for that
  * **Don't** register 20 interceptors — group related logic into fewer, well-named interceptors
</Callout>

***

## Next Steps

<Cards>
  <Card title="Caching" description="Improve performance with built-in response caching" href="/docs/caller/caching" />

  <Card title="Retries" description="Handle transient failures with automatic retry logic" href="/docs/caller/retries" />

  <Card title="Real-World Examples" description="See interceptors in production scenarios" href="/docs/caller/real-world-examples" />
</Cards>


---

# Retries

> Handle transient failures with automatic retry logic and backoff strategies. Make your application resilient to network issues and server errors.
URL: https://igniterjs.com/docs/caller/retries

Transient network issues or server overloads can cause temporary failures. Caller's built-in retry system helps make your application more resilient by automatically retrying failed requests with configurable backoff strategies.

***

## Basic Usage

Enable retries on any request using `.retry(maxAttempts, options?)`:

```typescript
// Retry up to 3 times (4 total attempts including the initial one)
const result = await api.get('/health')
  .retry(3)
  .execute();
```

The first parameter `maxAttempts` is the **number of retry attempts** — the initial request is always made, so total attempts = 1 + maxAttempts.

***

## Configuration

Customize retry behavior with the second parameter:

```typescript
await api.get('/external-service')
  .retry(5, {
    baseDelay: 500,           // Initial delay in ms (default: 1000)
    backoff: 'exponential',   // 'linear' or 'exponential' (default: 'linear')
    retryOnStatus: [502, 503], // Only retry on these status codes
  })
  .execute();
```

### Options

| Option          | Type                          | Default                          | Description                                        |
| --------------- | ----------------------------- | -------------------------------- | -------------------------------------------------- |
| `maxAttempts`   | number                        | (required)                       | Number of retry attempts. 3 = up to 4 total calls. |
| `backoff`       | `'linear'` \| `'exponential'` | `'linear'`                       | Delay strategy between retries                     |
| `baseDelay`     | number                        | `1000`                           | Initial delay in milliseconds                      |
| `retryOnStatus` | number\[]                     | `[408, 429, 500, 502, 503, 504]` | HTTP status codes that trigger retry               |

***

## Backoff Strategies

### Linear Backoff

Delay increases linearly: `baseDelay × attempt`

```
Attempt 1 (retry): 1000ms
Attempt 2 (retry): 2000ms
Attempt 3 (retry): 3000ms
```

```typescript
await api.get('/api')
  .retry(3, { backoff: 'linear', baseDelay: 1000 })
  .execute();
```

### Exponential Backoff

Delay doubles each attempt: `baseDelay × 2^(attempt - 1)`

```
Attempt 1 (retry): 1000ms  (1000 × 1)
Attempt 2 (retry): 2000ms  (1000 × 2)
Attempt 3 (retry): 4000ms  (1000 × 4)
```

```typescript
await api.get('/api')
  .retry(3, { backoff: 'exponential', baseDelay: 1000 })
  .execute();
```

<Callout type="info" title="When to use exponential">
  Use exponential backoff for upstream services that may be overwhelmed. It gives them time to recover without adding more load.
</Callout>

***

## Default Retry Status Codes

Caller retries on these status codes by default:

| Status | Meaning               | Why retry?                     |
| ------ | --------------------- | ------------------------------ |
| `408`  | Request Timeout       | Server timed out waiting       |
| `429`  | Too Many Requests     | Rate limit — retry after delay |
| `500`  | Internal Server Error | Transient server error         |
| `502`  | Bad Gateway           | Upstream server error          |
| `503`  | Service Unavailable   | Server overloaded              |
| `504`  | Gateway Timeout       | Upstream timeout               |

***

## Patterns

### Critical Operations with Retry + Fallback

```typescript
const { data } = await api.post('/payments')
  .body(paymentData)
  .headers({ 'X-Idempotency-Key': idempotencyKey })
  .retry(3, {
    backoff: 'exponential',
    baseDelay: 500,
    retryOnStatus: [408, 429, 502, 503, 504],
  })
  .fallback(() => ({ status: 'pending', retryLater: true }))
  .execute();
```

### Health Checks with Short Retry

```typescript
const { data } = await api.get('/health')
  .retry(2, {
    baseDelay: 200,
    backoff: 'linear',
    retryOnStatus: [502, 503],
  })
  .timeout(3000)
  .execute();
```

### External API with Aggressive Retry

```typescript
const { data } = await api.get('/third-party/data')
  .retry(5, {
    backoff: 'exponential',
    baseDelay: 1000,
  })
  .timeout(30_000)
  .execute();
```

***

## Idempotency Considerations

<Callout type="warn" title="Safety First — Non-Idempotent Requests">
  Be very careful when retrying **POST**, **PATCH**, and **PUT** requests that aren't idempotent. If a request succeeds but the response fails, a retry could create duplicate resources.

  Always use **idempotency keys** for critical operations:
</Callout>

```typescript
// ✅ Safe — with idempotency key
await api.post('/orders')
  .headers({ 'X-Idempotency-Key': `order-${userId}-${Date.now()}` })
  .body(orderData)
  .retry(3)
  .execute();

// ⚠️ Risky — without idempotency key
await api.post('/orders')
  .body(orderData)
  .retry(3) // Could create duplicate orders!
  .execute();
```

**Safe to retry without extra precautions:**

* `GET` — reads are idempotent by definition
* `HEAD` — no body, safe to retry
* `DELETE` — idempotent (deleting something twice has the same effect)
* `PUT` — idempotent by definition (replaces entire resource)

**Use idempotency keys for:**

* `POST` — creating resources
* `PATCH` — partial updates (may not be idempotent)

***

## Observability

Every retry attempt emits a telemetry event:

```typescript
// Event: igniter.caller.retry.attempt.started
// Attributes:
//   ctx.retry.attempt: number     — which attempt (1-based)
//   ctx.retry.maxAttempts: number — total allowed retries
//   ctx.retry.delayMs: number     — delay before this attempt
//   ctx.request.method: string    — HTTP method
//   ctx.request.url: string       — request URL
```

```typescript
import { IgniterCallerTelemetryEvents } from '@igniter-js/caller/telemetry';

// Monitor retry frequency in production
telemetry.on('igniter.caller.retry.attempt.started', (event) => {
  metrics.increment('api.retries', {
    method: event.attributes['ctx.request.method'],
    attempt: event.attributes['ctx.retry.attempt'],
  });
});
```

***

## Retry + Telemetry Example

```typescript
import { IgniterTelemetry } from '@igniter-js/telemetry';
import { IgniterCallerTelemetryEvents } from '@igniter-js/caller/telemetry';
import { IgniterCaller } from '@igniter-js/caller';

const telemetry = IgniterTelemetry.create()
  .withService('my-service')
  .addEvents(IgniterCallerTelemetryEvents)
  .build();

const api = IgniterCaller.create()
  .withBaseUrl('https://api.example.com')
  .withTelemetry(telemetry)
  .build();

// Retries will emit: igniter.caller.retry.attempt.started
const { data } = await api.get('/critical-data')
  .retry(3, { backoff: 'exponential' })
  .execute();
```

***

## Best Practices

<Callout type="success" title="Retry Guidelines">
  * **Use idempotency keys** for POST/PATCH requests
  * **Start with linear backoff** — switch to exponential if the service is frequently overloaded
  * **Set reasonable timeouts** — combine `.retry()` with `.timeout()` to avoid hanging
  * **Use fallback values** — `.fallback()` for non-critical data when all retries fail
  * **Monitor retry rates** — high retry frequency indicates a systemic issue
  * **Keep maxAttempts low** — 3-5 retries is usually enough; beyond that, the service is likely down
</Callout>

<Callout type="warn" title="Common Mistakes">
  * **Don't** retry indefinitely — set a reasonable `maxAttempts`
  * **Don't** retry `400 Bad Request` — client errors won't fix themselves
  * **Don't** use exponential backoff with very short `baseDelay` — it defeats the purpose
  * **Don't** retry without a timeout — the total wait could be very long
</Callout>

***

## Next Steps

<Cards>
  <Card title="Caching" description="Cache responses for better performance" href="/docs/caller/caching" />

  <Card title="Interceptors" description="Transform requests and responses globally" href="/docs/caller/interceptors" />

  <Card title="Telemetry" description="Monitor retry events and request performance" href="/docs/caller/telemetry" />
</Cards>


---

# Request Builder

> Master the fluent API for building type-safe HTTP requests. Learn how to configure URLs, bodies, headers, timeouts, caching, retries, and more with chainable methods.
URL: https://igniterjs.com/docs/caller/builder

## Overview

The **Request Builder** is the heart of Caller's developer experience. Instead of passing complex configuration objects, you chain methods together to build your request step by step. Each method returns the builder, enabling a fluid, readable syntax.

```typescript
const response = await api.post('/users')
  .body({ name: 'John', email: 'john@example.com' })
  .headers({ 'X-Idempotency-Key': crypto.randomUUID() })
  .timeout(5000)
  .retry(3, { backoff: 'exponential' })
  .execute();
```

Every method in the chain is optional. Use only what you need.

***

## Starting a Request

Requests begin by calling an HTTP method on your API client:

```typescript
// All methods return an IgniterCallerRequestBuilder
const getBuilder = api.get('/users');
const postBuilder = api.post('/users');
const putBuilder = api.put('/users/:id');
const patchBuilder = api.patch('/users/:id');
const deleteBuilder = api.delete('/users/:id');
const headBuilder = api.head('/status');
```

The HTTP method is locked once you start — you can't change a GET to a POST later. This ensures type safety throughout the chain.

<Callout type="info" title="URL Parameters">
  The `:id` syntax lets you define parameterized URLs. Fill them in with `.params()`. Extra params become query string parameters.
</Callout>

***

## Core Methods

<Accordions>
  <Accordion title=".url(url: string)">
    Sets the request URL or path. Useful when the URL isn't known at the time you call the HTTP method.

    ```typescript
    const result = await api.get()
      .url('/users')
      .params({ page: 1 })
      .execute();
    ```
  </Accordion>

  <Accordion title=".params(params)">
    Fills in URL path parameters and query string parameters.

    ```typescript
    // Path parameters: /users/:id/posts/:postId
    await api.get('/users/:id/posts/:postId')
      .params({ id: '123', postId: '456' })
      .execute();
    // Final URL: /users/123/posts/456

    // Query string: extra params become query parameters
    await api.get('/users')
      .params({ page: 1, limit: 20, status: 'active' })
      .execute();
    // Final URL: /users?page=1&limit=20&status=active
    ```

    When using schemas, TypeScript enforces that all path parameters are provided.
  </Accordion>

  <Accordion title=".body(data)">
    Sets the request body for POST, PUT, and PATCH requests. Objects and arrays are automatically serialized to JSON.

    ```typescript
    await api.post('/users')
      .body({
        name: 'John Doe',
        email: 'john@example.com',
      })
      .execute();
    ```

    **Raw Bodies:** For FormData, Blobs, URLSearchParams, or other types, use the same `.body()` method. Caller detects the body type and sets `Content-Type` automatically.

    ```typescript
    // FormData — Content-Type: multipart/form-data
    const formData = new FormData();
    formData.append('file', file);
    await api.post('/upload').body(formData).execute();

    // URLSearchParams — Content-Type: application/x-www-form-urlencoded
    const params = new URLSearchParams({ username: 'john', password: 'secret' });
    await api.post('/login').body(params).execute();
    ```

    **GET with body:** For GET and HEAD requests, body data is automatically converted to query parameters.
  </Accordion>

  <Accordion title=".headers(headers)">
    Adds per-request headers. These merge with (and override) default headers from the client configuration.

    ```typescript
    await api.post('/orders')
      .headers({
        'X-Idempotency-Key': crypto.randomUUID(),
        'Authorization': `Bearer ${accessToken}`,
      })
      .body(orderData)
      .execute();
    ```

    **Header Precedence:**

    1. Default headers from `IgniterCaller.create().withHeaders()`
    2. Per-request headers from `.headers()`
    3. Auto-generated headers (`Content-Type`, etc.)

    Per-request headers override defaults with the same name.
  </Accordion>

  <Accordion title=".timeout(ms)">
    Sets a timeout for this specific request in milliseconds (default: 30,000).

    ```typescript
    // Short timeout for health checks
    await api.get('/health').timeout(2000).execute();

    // Long timeout for file uploads
    await api.post('/upload').body(largeFile).timeout(60_000).execute();
    ```

    On timeout, the request fails with an `IGNITER_CALLER_TIMEOUT` error:

    ```typescript
    const { error } = await api.get('/slow-endpoint').timeout(1000).execute();
    if (error && IgniterCallerError.is(error) && error.code === 'IGNITER_CALLER_TIMEOUT') {
      console.log('Request timed out');
    }
    ```
  </Accordion>
</Accordions>

***

## Resilience Methods

<Accordions>
  <Accordion title=".retry(maxAttempts, options?)">
    Configures automatic retry behavior for transient failures. The first parameter is the **number of retry attempts** (total calls = 1 + maxAttempts).

    ```typescript
    await api.get('/external-api')
      .retry(3, {
        backoff: 'exponential',
        baseDelay: 500,
        retryOnStatus: [502, 503, 504],
      })
      .execute();
    ```

    **Options:**

    | Option          | Type                          | Default                          | Description              |
    | --------------- | ----------------------------- | -------------------------------- | ------------------------ |
    | `backoff`       | `'linear'` \| `'exponential'` | `'linear'`                       | Delay strategy           |
    | `baseDelay`     | number                        | 1000                             | Initial delay in ms      |
    | `retryOnStatus` | number\[]                     | `[408, 429, 500, 502, 503, 504]` | Status codes to retry on |

    **Backoff Strategies:**

    * `linear`: delay = baseDelay × attempt
    * `exponential`: delay = baseDelay × 2^(attempt - 1)

    <Callout type="warn" title="Non-idempotent requests">
      Be cautious when retrying POST/PATCH requests. Use idempotency keys to prevent duplicate operations.
    </Callout>
  </Accordion>

  <Accordion title=".fallback(factoryFn)">
    Provides a **factory function** that returns a fallback value if all retries fail. The result is returned as `data` with no error.

    ```typescript
    const { data } = await api.get('/feature-flags')
      .fallback(() => ({ darkMode: false, newUI: false }))
      .execute();

    // data is always defined, even on failure
    console.log(data.darkMode);
    ```

    <Callout type="info" title="Fallback is a factory, not a value">
      Use `.fallback(() => defaultValue)` — the factory is only called if the request actually fails.
    </Callout>
  </Accordion>

  <Accordion title=".cache(strategy, key?)">
    Sets the fetch `RequestCache` strategy and an optional custom cache key for programmatic invalidation.

    ```typescript
    // Standard fetch cache strategies
    await api.get('/data')
      .cache('force-cache')
      .execute();

    // Custom key for manual invalidation
    await api.get('/users')
      .cache('default', 'users:list')
      .stale(60_000)
      .execute();
    ```

    Valid strategies: `'default'`, `'no-store'`, `'reload'`, `'force-cache'`, `'only-if-cached'`.
  </Accordion>

  <Accordion title=".stale(milliseconds)">
    Enables response caching for the specified duration in milliseconds. Subsequent identical requests within the stale window return cached data without a network call.

    ```typescript
    // Cache for 30 seconds
    const { data } = await api.get('/users')
      .stale(30_000)
      .execute();

    // Second call (within 30s) returns cached data instantly
    const { data: cached } = await api.get('/users')
      .stale(30_000)
      .execute();

    // Cache for 5 minutes with a custom key
    const { data } = await api.get('/config')
      .cache('default', 'app:config')
      .stale(300_000)
      .execute();
    ```

    <Callout type="info" title="Invalidation">
      Cache is automatically invalidated after the stale time expires. For programmatic invalidation, use `IgniterCallerManager.on()` to observe mutations and clear relevant keys.
    </Callout>
  </Accordion>
</Accordions>

***

## Response Methods

<Accordions>
  <Accordion title=".responseType<T>(schema?)">
    Explicitly sets the expected response type for TypeScript inference. If a Zod or StandardSchemaV1 schema is passed, the response is **validated at runtime** (JSON/XML/CSV only). If only a type parameter is provided, it's for typing only with no runtime validation.

    ```typescript
    import { z } from 'zod';

    const UserSchema = z.object({
      id: z.string(),
      name: z.string(),
    });

    // With Zod schema — validates at runtime (only for JSON/XML/CSV)
    const { data } = await api.get('/users/:id')
      .params({ id: '123' })
      .responseType(UserSchema)
      .execute();
    // data is validated and typed

    // With type marker — typing only, no validation
    const { data: blob } = await api.get('/files/:id')
      .responseType<Blob>()
      .execute();

    // For streams
    const { data: stream } = await api.get('/events')
      .responseType<ReadableStream>()
      .execute();
    ```

    **Content-Type Detection:** Caller auto-detects the response content type from headers. Schema validation only runs for text-based content types (`application/json`, `text/xml`/`application/xml`, `text/csv`). Binary responses are returned as-is.
  </Accordion>
</Accordions>

***

## Executing Requests

The `.execute()` method sends the request and returns a Promise:

```typescript
const result = await api.get('/users').execute();
```

### Response Envelope

| Property  | Type                        | Description                               |
| --------- | --------------------------- | ----------------------------------------- |
| `data`    | `T \| undefined`            | Parsed response body. Undefined on error. |
| `error`   | `IgniterError \| undefined` | Error object. Undefined on success.       |
| `status`  | `number \| undefined`       | HTTP status code.                         |
| `headers` | `Headers \| undefined`      | Response headers.                         |

### Error Handling Patterns

```typescript
// Pattern 1: Guard clause (most common)
const { data, error } = await api.get('/users').execute();
if (error) {
  console.error(`${error.code}: ${error.message}`);
  return;
}
console.log(data); // TypeScript narrows data to T

// Pattern 2: Fallback for safe defaults
const { data } = await api.get('/optional-data')
  .fallback(() => ({ default: true }))
  .execute();
// data is always defined

// Pattern 3: Match on status
const result = await api.post('/users').body(payload).execute();
switch (result.status) {
  case 201: return result.data;
  case 400: throw new ValidationError(result.error!);
  case 409: throw new ConflictError(result.error!);
  default: throw result.error;
}
```

***

## Execution Pipeline

When you call `.execute()`, Caller runs through this pipeline:

1. **Cache Check** — If `.stale()` is set and a cached response exists, return it immediately
2. **Request Interceptors** — Run all registered request interceptors in order
3. **Schema Validation (Request)** — If schemas are configured, validate the request body
4. **Fetch with Retry** — Send the request; retry on failure according to `.retry()` config
5. **Response Parsing** — Auto-detect content type and parse (JSON, text, blob, etc.)
6. **Schema Validation (Response)** — If schemas are configured and content type is validatable, validate the response
7. **Response Interceptors** — Run all registered response interceptors in order
8. **Cache Store** — If `.stale()` is set and the request succeeded, store in cache
9. **Fallback** — If the request failed and `.fallback()` is configured, return the fallback value
10. **Telemetry Emission** — Emit success/error telemetry events

***

## Complete Example

Here's a production-ready example combining multiple builder methods:

```typescript
import { api } from '@/lib/api';
import { IgniterCallerError } from '@igniter-js/caller';

async function createOrder(items: CartItem[], userId: string) {
  const { data, error, status } = await api.post('/orders')
    .body({
      userId,
      items: items.map(item => ({
        productId: item.id,
        quantity: item.quantity,
      })),
      metadata: {
        source: 'web',
        timestamp: new Date().toISOString(),
      },
    })
    .headers({
      'X-Idempotency-Key': `order-${userId}-${Date.now()}`,
    })
    .timeout(10_000)
    .retry(2, {
      backoff: 'linear',
      retryOnStatus: [502, 503],
    })
    .execute();

  if (error) {
    if (status === 400) {
      return { success: false, message: 'Invalid order data', details: error.details };
    }
    if (status === 409) {
      return { success: false, message: 'Duplicate order' };
    }
    throw error; // Unexpected error — propagate
  }

  return { success: true, orderId: data!.id };
}
```

***

## Best Practices

<Callout type="success" title="Builder Method Order">
  While methods can be called in any order, we recommend this sequence for readability:

  1. `.url()` — URL configuration (if not set by HTTP method)
  2. `.params()` — Path and query parameters
  3. `.body()` — Request payload
  4. `.headers()` — Custom headers
  5. `.timeout()` — Timing configuration
  6. `.retry()`, `.cache()`, `.stale()` — Resilience
  7. `.responseType()` — Response typing
  8. `.execute()` — Always last
</Callout>

<Callout type="warn" title="Common Mistakes">
  * **Don't** call `.execute()` before `.retry()` — the request executes immediately
  * **Don't** use `.query()` — it doesn't exist. Use `.params()` for both path and query params
  * **Do** use `.fallback(() => value)` — it's a factory function, not a plain value
  * **Do** check for `error` before accessing `data` — `data` is `undefined` on failure
</Callout>

***

## Next Steps

<Cards>
  <Card title="Caller Manager" description="Learn about the runtime engine, batch requests, and global events" href="/docs/caller/manager" />

  <Card title="HTTP Methods" description="Deep dive into response parsing and content types" href="/docs/caller/methods" />

  <Card title="Schema Validation" description="Add type-safe validation to your requests" href="/docs/caller/schemas" />

  <Card title="API Reference" description="Complete reference for all classes, methods, and types" href="/docs/caller/api-reference" />
</Cards>


---

# Caller Manager

> The runtime engine that executes HTTP requests. Learn about global configuration, event handling, batch requests, and cache invalidation.
URL: https://igniterjs.com/docs/caller/manager

## Overview

The **IgniterCallerManager** is the runtime engine behind every Caller instance. When you call `.build()` on your configuration, you receive a manager that handles all the heavy lifting: executing requests, managing interceptors, emitting events, and coordinating caching.

While the Request Builder focuses on configuring individual requests, the Manager provides global capabilities that affect all requests or operate outside the request lifecycle.

```typescript
import { IgniterCallerManager } from '@igniter-js/caller';

// Your api instance IS a manager
const api = IgniterCaller.create()
  .withBaseUrl('https://api.example.com')
  .build();

// Manager-level operations
IgniterCallerManager.on('response', handleResponse);
IgniterCallerManager.invalidate('users:*');
```

***

## Instance vs Static Methods

The Manager exposes two types of methods:

| Type         | Access                      | Purpose                              |
| ------------ | --------------------------- | ------------------------------------ |
| **Instance** | `api.get()`, `api.post()`   | Creating requests for this client    |
| **Static**   | `IgniterCallerManager.on()` | Global operations across all clients |

This design allows you to have multiple independent API clients while still coordinating global behaviors like event handling and cache invalidation.

```typescript
// Two independent clients
const apiV1 = IgniterCaller.create().withBaseUrl('/api/v1').build();
const apiV2 = IgniterCaller.create().withBaseUrl('/api/v2').build();

// Global event listener applies to BOTH
IgniterCallerManager.on('response', (event) => {
  console.log(`Response from ${event.url}: ${event.status}`);
});
```

***

## Creating Requests

The manager provides convenience methods for all HTTP verbs:

<Accordions>
  <Accordion title="api.get(path)">
    Creates a GET request builder. GET requests retrieve data without side effects.

    ```typescript
    // Simple fetch
    const { data } = await api.get('/users').execute();

    // With parameters
    const { data } = await api.get('/users/:id')
      .params({ id: '123' })
      .execute();

    // With query string
    const { data } = await api.get('/users')
      .query({ page: 1, limit: 20 })
      .execute();
    ```
  </Accordion>

  <Accordion title="api.post(path)">
    Creates a POST request builder. POST requests create new resources.

    ```typescript
    const { data } = await api.post('/users')
      .body({ name: 'John', email: 'john@example.com' })
      .execute();
    ```
  </Accordion>

  <Accordion title="api.put(path)">
    Creates a PUT request builder. PUT requests replace an entire resource.

    ```typescript
    const { data } = await api.put('/users/:id')
      .params({ id: '123' })
      .body({ name: 'John Updated', email: 'john@example.com' })
      .execute();
    ```
  </Accordion>

  <Accordion title="api.patch(path)">
    Creates a PATCH request builder. PATCH requests update part of a resource.

    ```typescript
    const { data } = await api.patch('/users/:id')
      .params({ id: '123' })
      .body({ name: 'John Updated' }) // Only updating name
      .execute();
    ```
  </Accordion>

  <Accordion title="api.delete(path)">
    Creates a DELETE request builder. DELETE requests remove resources.

    ```typescript
    const { error } = await api.delete('/users/:id')
      .params({ id: '123' })
      .execute();

    if (!error) {
      console.log('User deleted successfully');
    }
    ```
  </Accordion>

  <Accordion title="api.request(config)">
    Low-level method for when you need full control. Accepts an axios-style config object.

    ```typescript
    const { data } = await api.request({
      method: 'POST',
      url: '/custom-endpoint',
      headers: { 'X-Custom': 'value' },
      body: { data: 'payload' },
      timeout: 5000,
    });
    ```

    Use this when the fluent builder doesn't cover your use case.
  </Accordion>
</Accordions>

***

## Batch Requests

Execute multiple requests in parallel with automatic error handling:

```typescript
const results = await IgniterCallerManager.batch([
  api.get('/users').execute(),
  api.get('/posts').execute(),
  api.get('/comments').execute(),
]);

// results is an array of { data, error, status } objects
const [users, posts, comments] = results;

if (users.error) {
  console.log('Failed to fetch users');
} else {
  console.log(`Fetched ${users.data.length} users`);
}
```

### Batch with Settlement

Batch requests use `Promise.allSettled` semantics—one failure doesn't abort the others:

```typescript
const results = await IgniterCallerManager.batch([
  api.get('/always-works').execute(),
  api.get('/sometimes-fails').execute(),
  api.get('/always-works-2').execute(),
]);

// Even if the second request fails, you get results from all three
results.forEach((result, index) => {
  if (result.error) {
    console.log(`Request ${index} failed: ${result.error.message}`);
  } else {
    console.log(`Request ${index} succeeded`);
  }
});
```

### Typed Batch Results

For type safety with heterogeneous requests, use the generic form:

```typescript
const [usersResult, postsResult] = await IgniterCallerManager.batch<
  [User[], Post[]]
>([
  api.get('/users').execute(),
  api.get('/posts').execute(),
]);

// usersResult.data is User[] | null
// postsResult.data is Post[] | null
```

***

## Global Events

Subscribe to events across all Caller instances for logging, analytics, or error tracking:

<Accordions>
  <Accordion title="IgniterCallerManager.on(event, handler)">
    Subscribes to global events. Returns an unsubscribe function.

    ```typescript
    const unsubscribe = IgniterCallerManager.on('response', (event) => {
      console.log(`[${event.method}] ${event.url} → ${event.status}`);
      
      // Send to analytics
      analytics.track('api_call', {
        url: event.url,
        method: event.method,
        status: event.status,
        duration: event.duration,
      });
    });

    // Later: stop listening
    unsubscribe();
    ```

    **Available Events:**

    | Event        | Payload                             | Description             |
    | ------------ | ----------------------------------- | ----------------------- |
    | `request`    | `{ url, method, headers }`          | Before request is sent  |
    | `response`   | `{ url, method, status, duration }` | After response received |
    | `error`      | `{ url, method, error }`            | When request fails      |
    | `cache:hit`  | `{ url, key }`                      | Cache hit occurred      |
    | `cache:miss` | `{ url, key }`                      | Cache miss occurred     |
  </Accordion>

  <Accordion title="IgniterCallerManager.off(event, handler)">
    Removes a specific event handler. Alternatively, use the unsubscribe function returned by `.on()`.

    ```typescript
    function myHandler(event) {
      console.log(event);
    }

    // Subscribe
    IgniterCallerManager.on('response', myHandler);

    // Unsubscribe
    IgniterCallerManager.off('response', myHandler);
    ```
  </Accordion>
</Accordions>

### Event Handler Examples

```typescript
// Error tracking
IgniterCallerManager.on('error', (event) => {
  Sentry.captureException(event.error, {
    tags: { url: event.url, method: event.method },
  });
});

// Performance monitoring
IgniterCallerManager.on('response', (event) => {
  if (event.duration > 1000) {
    console.warn(`Slow request: ${event.url} took ${event.duration}ms`);
  }
});

// Debug logging in development
if (process.env.NODE_ENV === 'development') {
  IgniterCallerManager.on('request', (e) => console.log('→', e.method, e.url));
  IgniterCallerManager.on('response', (e) => console.log('←', e.status, e.url));
}
```

***

## Cache Invalidation

Programmatically invalidate cached responses when data changes:

<Accordions>
  <Accordion title="IgniterCallerManager.invalidate(key)">
    Invalidates a specific cache entry by its exact key.

    ```typescript
    // Cache a response with a key
    await api.get('/users')
      .cache({ key: 'users:list', ttl: 300 })
      .execute();

    // After creating a new user, invalidate the cache
    await api.post('/users').body(newUser).execute();
    IgniterCallerManager.invalidate('users:list');

    // Next request will fetch fresh data
    const { data } = await api.get('/users')
      .cache({ key: 'users:list', ttl: 300 })
      .execute();
    ```
  </Accordion>

  <Accordion title="IgniterCallerManager.invalidatePattern(pattern)">
    Invalidates multiple cache entries matching a glob pattern.

    ```typescript
    // Invalidate all user-related caches
    IgniterCallerManager.invalidatePattern('users:*');

    // Invalidate all caches for a specific user
    IgniterCallerManager.invalidatePattern('*:user:123:*');

    // Clear all caches (use with caution!)
    IgniterCallerManager.invalidatePattern('*');
    ```

    **Pattern Syntax:**

    * `*` matches any characters within a segment
    * `users:*` matches `users:list`, `users:123`, etc.
    * `*:user:*` matches `api:user:123`, `cache:user:456`, etc.
  </Accordion>
</Accordions>

### Cache Invalidation Patterns

```typescript
// Pattern 1: Invalidate on mutation
async function createUser(data: CreateUserInput) {
  const { data: user, error } = await api.post('/users')
    .body(data)
    .execute();
  
  if (!error) {
    IgniterCallerManager.invalidate('users:list');
  }
  
  return user;
}

// Pattern 2: Invalidate related data
async function updateUserProfile(userId: string, data: ProfileInput) {
  await api.patch('/users/:id/profile')
    .params({ id: userId })
    .body(data)
    .execute();
  
  // Invalidate multiple related caches
  IgniterCallerManager.invalidate(`users:${userId}`);
  IgniterCallerManager.invalidate(`users:${userId}:profile`);
  IgniterCallerManager.invalidate('users:list'); // List might show profile data
}

// Pattern 3: React hook integration
function useCreateUser() {
  const queryClient = useQueryClient();
  
  return async (data: CreateUserInput) => {
    const { data: user } = await api.post('/users').body(data).execute();
    
    // Invalidate Caller cache
    IgniterCallerManager.invalidate('users:list');
    
    // Invalidate React Query cache (if using both)
    queryClient.invalidateQueries(['users']);
    
    return user;
  };
}
```

***

## Common Patterns

<Accordions>
  <Accordion title="Request Logging Middleware">
    Create a logging layer that captures all API activity:

    ```typescript
    // lib/api-logger.ts
    export function setupApiLogging() {
      IgniterCallerManager.on('request', (event) => {
        console.log(`[API] → ${event.method} ${event.url}`);
      });
      
      IgniterCallerManager.on('response', (event) => {
        const emoji = event.status < 400 ? '✓' : '✗';
        console.log(`[API] ${emoji} ${event.status} ${event.url} (${event.duration}ms)`);
      });
      
      IgniterCallerManager.on('error', (event) => {
        console.error(`[API] ✗ ${event.method} ${event.url}`, event.error);
      });
    }

    // Call once at app startup
    setupApiLogging();
    ```
  </Accordion>

  <Accordion title="Offline Detection">
    Detect when the user goes offline and queue requests:

    ```typescript
    let isOnline = navigator.onLine;
    const pendingRequests: Array<() => Promise<void>> = [];

    window.addEventListener('online', async () => {
      isOnline = true;
      // Replay queued requests
      while (pendingRequests.length > 0) {
        const request = pendingRequests.shift();
        await request?.();
      }
    });

    window.addEventListener('offline', () => {
      isOnline = false;
    });

    IgniterCallerManager.on('error', (event) => {
      if (!isOnline && event.error.code === 'NETWORK_ERROR') {
        // Queue for retry when online
        pendingRequests.push(() => 
          api.request({ url: event.url, method: event.method }).execute()
        );
      }
    });
    ```
  </Accordion>
</Accordions>

***

## Best Practices

<Callout type="success" title="Manager Guidelines">
  1. **Use instance methods for requests** — `api.get()`, `api.post()`, etc.
  2. **Use static methods for global operations** — events, invalidation
  3. **Set up event handlers early** — typically in your app's entry point
  4. **Clean up subscriptions** — especially in React useEffect or component unmount
  5. **Use meaningful cache keys** — makes invalidation patterns clearer
</Callout>

***

## Next Steps

<Cards>
  <Card title="HTTP Methods" description="Learn about response parsing and content types" href="/docs/caller/methods" />

  <Card title="Caching" description="Deep dive into caching strategies" href="/docs/caller/caching" />

  <Card title="Interceptors" description="Add middleware to all requests" href="/docs/caller/interceptors" />
</Cards>


---

# HTTP Methods & Response Parsing

> Deep dive into HTTP method handling, automatic content-type detection, and response parsing strategies. Learn how Caller processes different data formats.
URL: https://igniterjs.com/docs/caller/methods

## Overview

Caller supports all standard HTTP methods and automatically handles response parsing based on content type. You don't need to manually call `.json()` or `.text()`—Caller detects the response format and deserializes it appropriately.

This automatic handling covers JSON, XML, plain text, form data, and binary responses. For cases where automatic detection isn't enough, you have full control over response parsing.

***

## HTTP Methods

Every HTTP method has specific semantics. Understanding these helps you build correct, RESTful APIs:

| Method      | Purpose            | Body     | Idempotent | Safe |
| ----------- | ------------------ | -------- | ---------- | ---- |
| **GET**     | Retrieve data      | No       | Yes        | Yes  |
| **POST**    | Create resource    | Yes      | No         | No   |
| **PUT**     | Replace resource   | Yes      | Yes        | No   |
| **PATCH**   | Update resource    | Yes      | No         | No   |
| **DELETE**  | Remove resource    | Optional | Yes        | No   |
| **HEAD**    | Get headers only   | No       | Yes        | Yes  |
| **OPTIONS** | Check capabilities | No       | Yes        | Yes  |

<Accordions>
  <Accordion title="GET — Retrieving Data">
    GET requests fetch data without side effects. They should be safe to repeat without changing server state.

    ```typescript
    // Fetch a list
    const { data: users } = await api.get('/users')
      .params({ status: 'active', limit: 50 })
      .execute();

    // Fetch a single resource
    const { data: user } = await api.get('/users/:id')
      .params({ id: '123' })
      .execute();

    // GET requests are cacheable by default
    const { data } = await api.get('/config')
      .cache({ ttl: 3600 })
      .execute();
    ```

    **Best Practices:**

    * Use query parameters for filtering, not path parameters
    * Keep URLs under 2000 characters
    * Don't put sensitive data in query strings (use headers)
  </Accordion>

  <Accordion title="POST — Creating Resources">
    POST requests create new resources. Each call typically creates a new entity.

    ```typescript
    const { data: newUser, status } = await api.post('/users')
      .body({
        name: 'John Doe',
        email: 'john@example.com',
      })
      .execute();

    // status === 201 for successful creation
    if (status === 201) {
      console.log('Created user:', newUser.id);
    }
    ```

    **Idempotency Keys:**
    For critical operations, use idempotency keys to prevent duplicates:

    ```typescript
    const { data } = await api.post('/orders')
      .headers({ 'X-Idempotency-Key': `order-${userId}-${Date.now()}` })
      .body(orderData)
      .execute();
    ```
  </Accordion>

  <Accordion title="PUT — Replacing Resources">
    PUT requests replace an entire resource. You must send the complete entity.

    ```typescript
    // Replace the entire user object
    const { data } = await api.put('/users/:id')
      .params({ id: '123' })
      .body({
        name: 'John Updated',
        email: 'john@example.com',
        role: 'admin',
        // ALL fields are required
      })
      .execute();
    ```

    PUT is idempotent—calling it multiple times with the same data produces the same result.
  </Accordion>

  <Accordion title="PATCH — Partial Updates">
    PATCH requests update specific fields without requiring the full resource.

    ```typescript
    // Update only the name
    const { data } = await api.patch('/users/:id')
      .params({ id: '123' })
      .body({ name: 'John Updated' })
      .execute();
    ```

    Common PATCH formats:

    * **JSON Merge Patch** (RFC 7396): Send only changed fields
    * **JSON Patch** (RFC 6902): Array of operations

    ```typescript
    // RFC 7396: Merge Patch
    await api.patch('/users/:id')
      .headers({ 'Content-Type': 'application/merge-patch+json' })
      .body({ name: 'New Name', email: null }) // null removes the field
      .execute();

    // RFC 6902: JSON Patch
    await api.patch('/users/:id')
      .headers({ 'Content-Type': 'application/json-patch+json' })
      .body([
        { op: 'replace', path: '/name', value: 'New Name' },
        { op: 'remove', path: '/email' },
      ])
      .execute();
    ```
  </Accordion>

  <Accordion title="DELETE — Removing Resources">
    DELETE requests remove resources. They should be idempotent.

    ```typescript
    const { error, status } = await api.delete('/users/:id')
      .params({ id: '123' })
      .execute();

    if (status === 204) {
      console.log('User deleted');
    }
    if (status === 404) {
      console.log('User not found (already deleted?)');
    }
    ```

    Some APIs return the deleted resource; others return 204 No Content:

    ```typescript
    // API returns deleted resource
    const { data: deletedUser } = await api.delete('/users/:id')
      .params({ id: '123' })
      .execute();

    // API returns 204 No Content
    const { status } = await api.delete('/users/:id')
      .params({ id: '123' })
      .execute();
    // data will be null for 204 responses
    ```
  </Accordion>
</Accordions>

***

## Automatic Response Parsing

Caller automatically parses responses based on the `Content-Type` header:

| Content-Type                    | Parsing         | Result Type                  |
| ------------------------------- | --------------- | ---------------------------- |
| `application/json`              | `JSON.parse()`  | Object/Array                 |
| `text/plain`                    | Raw string      | string                       |
| `text/html`                     | Raw string      | string                       |
| `application/xml`               | Parse to object | Object (if parser available) |
| `multipart/form-data`           | FormData        | FormData                     |
| `application/octet-stream`      | Blob            | Blob                         |
| `image/*`, `video/*`, `audio/*` | Blob            | Blob                         |

```typescript
// JSON response - automatically parsed
const { data } = await api.get('/api/users').execute();
// data is already a JavaScript object

// Text response - returned as string
const { data } = await api.get('/health').execute();
// data is "OK" (string)

// Binary response - returned as Blob
const { data } = await api.get('/files/123/download').execute();
// data is a Blob
```

***

## Explicit Response Types

When automatic detection isn't sufficient, explicitly specify the response type:

<Accordions>
  <Accordion title=".responseType<T>(schema?) — Custom Parsing">
    Explicitly sets the expected response type and optional runtime validation. While Caller auto-detects most types, you can force a specific parsing strategy or type inference.

    ```typescript
    // Force Blob response
    const { data: blob } = await api.get('/files/:id')
      .params({ id: 'abc123' })
      .responseType<Blob>()
      .execute();

    // Force ReadableStream
    const { data: stream } = await api.get('/events')
      .responseType<ReadableStream>()
      .execute();

    // Force JSON with explicit schema validation
    const { data: user } = await api.get('/me')
      .responseType(UserSchema)
      .execute();
    ```
  </Accordion>
</Accordions>

***

## Response Object

Every request returns a standardized response object:

```typescript
interface CallerResponse<T> {
  data: T | null;           // Parsed response body
  error: CallerError | null; // Error object if failed
  status: number;           // HTTP status code
  headers: Headers;         // Response headers
  isStale: boolean;         // True if from stale cache
}
```

### Working with Headers

```typescript
const { data, headers } = await api.get('/users').execute();

// Read specific headers
const rateLimitRemaining = headers.get('X-RateLimit-Remaining');
const etag = headers.get('ETag');

// Check for pagination headers
const totalCount = parseInt(headers.get('X-Total-Count') || '0');
const nextPage = headers.get('Link')?.match(/<([^>]+)>; rel="next"/)?.[1];
```

### Status Code Handling

```typescript
const { data, error, status } = await api.post('/users')
  .body(userData)
  .execute();

switch (status) {
  case 200:
    console.log('Updated existing user');
    break;
  case 201:
    console.log('Created new user:', data.id);
    break;
  case 400:
    console.error('Validation failed:', error?.message);
    break;
  case 401:
    redirectToLogin();
    break;
  case 403:
    console.error('Not authorized');
    break;
  case 404:
    console.error('Resource not found');
    break;
  case 409:
    console.error('Conflict - resource already exists');
    break;
  case 422:
    console.error('Unprocessable entity:', error?.details);
    break;
  case 429:
    console.error('Rate limited - retry after', error?.retryAfter);
    break;
  case 500:
  case 502:
  case 503:
    console.error('Server error - please try again');
    break;
}
```

***

## Content-Type Handling

### Request Content Types

Caller automatically sets the `Content-Type` header based on the body:

| Body Type       | Auto Content-Type                         |
| --------------- | ----------------------------------------- |
| Object/Array    | `application/json`                        |
| FormData        | `multipart/form-data`                     |
| URLSearchParams | `application/x-www-form-urlencoded`       |
| string          | `text/plain`                              |
| Blob            | Blob's type or `application/octet-stream` |

Override the automatic detection when needed:

```typescript
// Send XML
await api.post('/soap-api')
  .headers({ 'Content-Type': 'application/xml' })
  .body('<request><data>value</data></request>')
  .execute();

// Send form-urlencoded
const params = new URLSearchParams();
params.append('username', 'john');
params.append('password', 'secret');

await api.post('/login')
  .body(params)
  .execute();
```

### File Uploads

```typescript
// Single file
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('description', 'My document');

const { data } = await api.post('/upload')
  .body(formData)
  .execute();

// Multiple files
const formData = new FormData();
for (const file of fileInput.files) {
  formData.append('files', file);
}

const { data } = await api.post('/upload/multiple')
  .body(formData)
  .execute();
```

***

## Error Responses

When a request fails (status ≥ 400), Caller populates the `error` property:

```typescript
interface CallerError {
  code: string;           // Error code (e.g., 'HTTP_ERROR', 'TIMEOUT')
  message: string;        // Human-readable message
  status: number;         // HTTP status code
  details?: unknown;      // API-specific error details
  retryAfter?: number;    // Seconds to wait (for 429)
}
```

```typescript
const { data, error } = await api.get('/users/:id')
  .params({ id: 'invalid' })
  .execute();

if (error) {
  console.log(error.code);    // 'HTTP_ERROR'
  console.log(error.status);  // 404
  console.log(error.message); // 'Not Found'
  console.log(error.details); // { reason: 'User does not exist' }
}
```

***

## Best Practices

<Callout type="success" title="Response Handling Guidelines">
  1. **Always check for errors** — Never assume `data` is defined
  2. **Use explicit types for edge cases** — When Content-Type is unreliable
  3. **Handle all relevant status codes** — Don't catch-all to 'error'
  4. **Clean up Blobs** — Call `URL.revokeObjectURL()` after use
  5. **Stream large responses** — Don't load huge files into memory
</Callout>

***

## Next Steps

<Cards>
  <Card title="Schema Validation" description="Add type-safe response validation" href="/docs/caller/schemas" />

  <Card title="Error Handling" description="Advanced error handling patterns" href="/docs/caller/interceptors" />

  <Card title="Caching" description="Cache responses for better performance" href="/docs/caller/caching" />
</Cards>


---

# React Integration

> Using Caller in your React and Next.js applications. Covers queries, mutations, cache invalidation, global config, and SSR patterns.
URL: https://igniterjs.com/docs/caller/react

Caller provides a dedicated React client via the `@igniter-js/caller/client` subpath. This keeps the core library server-safe and avoids bundling React where it isn't needed.

***

## Setup

Wrap your application with `IgniterCallerProvider`:

```tsx title="app/providers.tsx"
import { IgniterCallerProvider } from '@igniter-js/caller/client';
import { api } from '@/lib/api';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <IgniterCallerProvider callers={{ main: api }}>
      {children}
    </IgniterCallerProvider>
  );
}
```

### Multiple API Clients

You can provide multiple named callers:

```tsx
<IgniterCallerProvider callers={{
  main: publicApi,
  admin: adminApi,
  payments: stripeApi,
}}>
  {children}
</IgniterCallerProvider>
```

***

## Creating a Typed Hook

Create a reusable typed hook for your app:

```typescript title="hooks/use-caller.ts"
import { useIgniterCaller } from '@igniter-js/caller/client';
import type { api, adminApi } from '@/lib/api';

// Define your callers
type Callers = {
  main: typeof api;
  admin: typeof adminApi;
};

// Export a typed hook
export const useCaller = useIgniterCaller<Callers>();
```

Now every consumer gets full type safety:

```tsx
function Dashboard() {
  const main = useCaller('main');
  //    ^? IgniterCallerClient<typeof api> — fully typed

  const { data } = main.get('/users').useQuery();
  //     ^? T | null — inferred from schema (if configured)
}
```

***

## Queries (GET/HEAD)

Use `.useQuery()` for data fetching:

```tsx
function UserProfile({ id }: { id: string }) {
  const main = useCaller('main');

  const {
    data,          // T | null — the fetched data
    error,         // IgniterError | null
    isLoading,     // true on initial load
    isFetching,    // true while fetching (including refetches)
    isSuccess,     // true when data was fetched successfully
    isError,       // true when the request failed
    status,        // 'loading' | 'success' | 'error'
    refetch,       // () => void — re-execute the query
    invalidate,    // (data?: T) => void — clear cache and refetch
    execute,       // (variables?) => Promise<ApiResponse<T>> — manual execution
  } = main.get('/users/:id')
    .params({ id })
    .useQuery({
      staleTime: 30_000,         // Cache for 30 seconds
      enabled: Boolean(id),       // Don't run if id is empty
      refetchOnMount: true,       // Refetch when component mounts (default: true)
      refetchOnWindowFocus: true, // Refetch on window focus (default: true)
      refetchInterval: 60_000,    // Auto-refetch every 60s
      refetchIntervalInBackground: false, // Don't refetch when tab is hidden
      initialData: null,          // Initial data before first fetch
    });
```

### Query Options

| Option                        | Type                            | Default | Description                                  |
| ----------------------------- | ------------------------------- | ------- | -------------------------------------------- |
| `staleTime`                   | number                          | —       | Cache duration in ms                         |
| `enabled`                     | boolean                         | `true`  | Set to `false` to disable automatic fetching |
| `params`                      | object                          | —       | URL path/query params                        |
| `headers`                     | object                          | —       | Per-request headers                          |
| `query`                       | object                          | —       | Query string parameters                      |
| `refetchOnMount`              | boolean                         | `true`  | Refetch when component mounts                |
| `refetchOnWindowFocus`        | boolean                         | `true`  | Refetch on window focus                      |
| `refetchInterval`             | number                          | —       | Auto-refetch interval in ms                  |
| `refetchIntervalInBackground` | boolean                         | `true`  | Refetch when tab is hidden                   |
| `initialData`                 | T                               | —       | Initial data before fetch                    |
| `onSuccess`                   | `(data: T) => void`             | —       | Called on successful fetch                   |
| `onError`                     | `(error: IgniterError) => void` | —       | Called on failed fetch                       |
| `onSettled`                   | `(data, error) => void`         | —       | Called after every fetch                     |
| `onRequest`                   | `(response) => void`            | —       | Called before processing                     |
| `onLoading`                   | `(loading: boolean) => void`    | —       | Called when loading state changes            |

### Query Lifecycle Callbacks

```tsx
const { data } = main.get('/me').useQuery({
  staleTime: 60_000,

  onSuccess(data) {
    console.log('Profile loaded:', data?.name);
  },

  onError(error) {
    if (error.code === 'IGNITER_CALLER_HTTP_ERROR') {
      console.error('Failed to load profile');
    }
  },

  onSettled(data, error) {
    // Always called — success or failure
    analytics.track('profile_loaded', { success: !error });
  },

  onLoading(loading) {
    // Called when loading state changes
    setGlobalLoading(loading);
  },
});
```

***

## Mutations (POST/PUT/PATCH/DELETE)

Mutations don't use `.useMutate()` directly on the builder — instead, use `.execute()` in event handlers, or use the `.useMutate()` helper provided by the client:

```tsx
function CreateUserForm() {
  const main = useCaller('main');

  const { mutate, isLoading, error, data } = main.post('/users')
    .useMutate({
      onSuccess(data) {
        // Invalidate queries that depend on this data
        main.invalidate('/users');
        toast.success('User created!');
      },
      onError(error) {
        toast.error(`Failed: ${error.message}`);
      },
    });

  const handleSubmit = (values: CreateUserInput) => {
    mutate({ body: values });
  };

  return (
    <form onSubmit={(e) => { e.preventDefault(); /* ... */ }}>
      {isLoading && <Spinner />}
      <button type="submit" disabled={isLoading}>Create User</button>
    </form>
  );
}
```

### useMutate Options

| Option      | Type                            | Description                       |
| ----------- | ------------------------------- | --------------------------------- |
| `onSuccess` | `(data: T) => void`             | Called on successful mutation     |
| `onError`   | `(error: IgniterError) => void` | Called on failed mutation         |
| `onSettled` | `(data, error) => void`         | Called after every mutation       |
| `onRequest` | `(response) => void`            | Called before processing          |
| `onLoading` | `(loading: boolean) => void`    | Called when loading state changes |

### Manual Mutation Pattern

For cases where you need more control:

```tsx
function DeleteUserButton({ userId }: { userId: string }) {
  const main = useCaller('main');
  const [isDeleting, setIsDeleting] = useState(false);

  const handleDelete = async () => {
    setIsDeleting(true);
    const { error } = await main.delete('/users/:id')
      .params({ id: userId })
      .execute();

    if (error) {
      toast.error('Failed to delete user');
    } else {
      main.invalidate('/users');
      toast.success('User deleted');
    }
    setIsDeleting(false);
  };

  return (
    <button onClick={handleDelete} disabled={isDeleting}>
      {isDeleting ? 'Deleting...' : 'Delete'}
    </button>
  );
}
```

***

## Cache Invalidation

The client exposes an `.invalidate()` method for clearing cached queries:

```tsx
function UpdateUserForm({ user }: { user: User }) {
  const main = useCaller('main');

  const handleSubmit = async (data: UpdateUserInput) => {
    const { error } = await main.patch('/users/:id')
      .params({ id: user.id })
      .body(data)
      .execute();

    if (!error) {
      // Invalidate specific queries
      main.invalidate(`/users/${user.id}`);    // Single user
      main.invalidate('/users');                // User list

      // Invalidate with data pre-population
      main.invalidate('/users', [{ ...user, ...data }]);

      // Invalidate multiple paths
      main.invalidate(['/users', '/dashboard']);
    }
  };
}
```

***

## Per-Caller Configuration

Dynamically configure headers, cookies, and query parameters per caller:

```tsx
function AuthenticatedApp() {
  const main = useCaller('main');

  useEffect(() => {
    // Set auth token on mount
    main.config.set('headers', {
      'Authorization': `Bearer ${token}`,
    });

    // Set default query params
    main.config.set('query', { version: '2' });

    return () => main.config.reset();
  }, [token]);
}
```

### Config API

| Method                   | Description                                        |
| ------------------------ | -------------------------------------------------- |
| `config.set(key, value)` | Set a config value (`headers`, `cookies`, `query`) |
| `config.get(key)`        | Get a merged config value                          |
| `config.reset()`         | Reset all per-caller config                        |

***

## Global Configuration

Pass global defaults to all callers via the provider:

```tsx
<IgniterCallerProvider
  callers={{ main: api, admin: adminApi }}
  hooks={{
    headers: { 'X-Client-Version': '2.0' },
    cookies: { theme: 'dark' },
    query: { lang: 'en' },
    onQuerySuccess(data) {
      console.log('Query succeeded:', data);
    },
    onQueryError(error) {
      console.error('Query failed:', error.message);
    },
    onMutationLoading(loading) {
      setGlobalLoading(loading);
    },
  }}
  onError={(error) => {
    // Global error handler for all callers
    if ((error as any).statusCode === 401) {
      redirectToLogin();
    }
  }}
>
  {children}
</IgniterCallerProvider>
```

### Global Config Merging

Per-caller config **merges with** global config. Per-caller values take precedence:

```
Global headers:   { 'X-Version': '2.0', 'Accept': 'application/json' }
Caller headers:   { 'Authorization': 'Bearer ...' }
─────────────────────────────────────────────────────────
Merged headers:   { 'X-Version': '2.0', 'Accept': 'application/json', 'Authorization': 'Bearer ...' }
```

***

## Raw Access

Need to escape the hook abstraction? Access the raw manager directly:

```tsx
function handleBulkOperation() {
  const main = useCaller('main');

  // Direct manager access — bypasses hooks
  const { data } = await main.raw.post('/bulk')
    .body(massivePayload)
    .timeout(60_000)
    .execute();
}
```

***

## Server Components (Next.js App Router)

In Server Components, use the standard Caller directly — no provider needed:

```typescript title="app/users/page.tsx"
import { api } from '@/lib/api-server';

export default async function UsersPage() {
  const { data: users } = await api.get('/users')
    .params({ limit: 20 })
    .stale(60_000)
    .execute();

  return (
    <ul>
      {users?.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}
```

<Callout type="info" title="Client vs Server">
  * **Server Components**: Use the standard `api.get().execute()` directly
  * **Client Components**: Use `useCaller()` with `.useQuery()` and `.useMutate()`
  * Import from `@igniter-js/caller/client` only in Client Components
</Callout>

***

## Testing React Components

```tsx
import { render, screen, waitFor } from '@testing-library/react';
import { IgniterCallerProvider } from '@igniter-js/caller/client';
import { IgniterCaller, IgniterCallerMock } from '@igniter-js/caller';

function renderWithCaller(ui: React.ReactElement) {
  const mock = IgniterCallerMock.create()
    .mock('/users', {
      GET: {
        response: [{ id: '1', name: 'Test User' }],
        status: 200,
      },
    })
    .build();

  const testApi = IgniterCaller.create()
    .withBaseUrl('https://test.api')
    .withMock({ enabled: true, mock })
    .build();

  return render(
    <IgniterCallerProvider callers={{ main: testApi }}>
      {ui}
    </IgniterCallerProvider>
  );
}

it('renders user list', async () => {
  renderWithCaller(<UserList />);
  await waitFor(() => {
    expect(screen.getByText('Test User')).toBeInTheDocument();
  });
});
```

***

## Best Practices

<Callout type="success" title="React Integration Guidelines">
  * **Create a typed hook** — `useIgniterCaller<Callers>()` for app-wide type safety
  * **Set stale times** — prevent unnecessary refetches on every render
  * **Use `enabled: false`** for conditional queries (e.g., waiting for a search term)
  * **Invalidate related queries** — after mutations, clear affected caches
  * **Handle errors globally** — use `onError` on the provider for common error handling
  * **Use Server Components** for data that can be fetched at request time
</Callout>

***

## Next Steps

<Cards>
  <Card title="Mocking & Testing" description="Test your React components with type-safe mock APIs" href="/docs/caller/testing" />

  <Card title="Real-World Examples" description="React patterns for authentication, pagination, and optimistic updates" href="/docs/caller/real-world-examples" />

  <Card title="Schema Validation" description="Add type-safe schemas to your React queries" href="/docs/caller/schemas" />

  <Card title="API Reference" description="Complete reference for the React client API" href="/docs/caller/api-reference" />
</Cards>


---

# dev

> Development mode with automatic schema and OpenAPI regeneration. File watching, Ink TUI, and integrated dev server — code and your types stay in sync.
URL: https://igniterjs.com/docs/cli/commands/dev

## `igniter dev`

The `dev` command starts a development environment that watches your router and features for changes, then automatically regenerates the client schema and OpenAPI specification. It also starts your development server and displays a split-pane terminal UI.

```bash
igniter dev [options]
```

***

## Options

| Option          | Type     | Default                 | Description                                    |
| --------------- | -------- | ----------------------- | ---------------------------------------------- |
| `--router`      | `string` | `src/igniter.router.ts` | Path to the router file to watch               |
| `--output`      | `string` | `src/igniter.schema.ts` | Output path for the client schema file         |
| `--docs-output` | `string` | `./src/docs`            | Output directory for the OpenAPI spec          |
| `--cmd`         | `string` | auto-detected           | Custom command to start the development server |

***

## How It Works

<Steps>
  <Step>
    ### Startup

    On launch, the CLI:

    1. **Detects the package manager** from `npm_config_user_agent`
    2. **Resolves paths** — router, schema output, docs output — relative to the project root
    3. **Validates** that the router file exists (exits with error if not found)
    4. **Generates initial output** — runs schema generation, then docs generation
    5. **Starts the dev server** using the `--cmd` flag or auto-detected default
  </Step>

  <Step>
    ### File Watching

    The CLI watches for changes using **chokidar** with a **300ms debounce**:

    * `src/igniter.router.ts` — the main router file
    * `src/features/` — all feature directories (recursive)

    **Ignored patterns:**

    * `node_modules/`
    * `.git/`
    * `dist/`
    * `.next/`
    * `.turbo/`
    * `.cache/`
    * `*.test.ts` / `*.spec.ts`
  </Step>

  <Step>
    ### Auto-Regeneration

    When a watched file changes:

    1. The debounce timer resets (300ms)
    2. After the debounce period, the CLI regenerates:
       * **Client schema** (`igniter.schema.ts`) — extracted from the router
       * **OpenAPI docs** (`src/docs/`) — generated from the router
    3. Results are logged to the TUI with timing and metadata

    ```bash
    # Example TUI output after regeneration:
    # ✅ Schema regenerated in 0.86s (12 controllers, 47 actions)
    # ✅ OpenAPI docs regenerated in 0.42s (23.4 KB)
    ```
  </Step>

  <Step>
    ### Dev Server Integration

    If `--cmd` is provided (or auto-detected), the CLI spawns the dev server as a child process:

    ```bash
    # Explicit command
    igniter dev --cmd "pnpm dev"

    # Auto-detected defaults:
    # npm  → "npm run dev"
    # pnpm → "pnpm dev"
    # yarn → "yarn dev"
    # bun  → "bun dev"
    ```

    The dev server's stdout and stderr are captured and displayed in the **App Logs** panel of the TUI.

    <Callout type="info">
      The dev server is started with `NODE_ENV=development` and runs in the project's working directory. If it exits with a non-zero code, a warning is logged to the TUI.
    </Callout>
  </Step>
</Steps>

***

## Terminal UI (TUI)

The dev command renders a **split-pane terminal UI** using [Ink](https://github.com/vadimdemedes/ink) (React for the terminal):

```
┌──────────────────────────────────────────────────────┐
│  Igniter Dev Mode                        [q] to quit  │
├──────────────────────┬───────────────────────────────┤
│   Igniter Logs       │       App Logs                 │
│                      │                                │
│  ✅ Schema regenera… │  > next dev                    │
│  ✅ OpenAPI docs re… │  ▲ Ready in 2.1s               │
│  ℹ File changed: …   │  ▲ Local: http://localhost:3000│
│  ✅ Schema regenera… │  GET /api/users 200 (45ms)     │
│                      │  POST /api/auth 201 (12ms)     │
│                      │                                │
└──────────────────────┴───────────────────────────────┘
```

* **Igniter Logs** (left panel): Schema regeneration, doc generation, file change events, errors
* **App Logs** (right panel): Your dev server output — Next.js, Express, etc.
* **Exit**: Press `q` or send `SIGINT` (Ctrl+C)

Logs are capped at **1,000 entries** per panel to prevent memory growth.

***

## Graceful Shutdown

The CLI registers cleanup handlers for `SIGINT` and `SIGTERM`:

1. Clears any pending debounce timeout
2. Closes the chokidar file watcher
3. Sends `SIGTERM` to the dev server process
4. Unmounts the Ink TUI
5. Exits with code 0

***

## Examples

### Standard Next.js Dev Mode

```bash
cd my-nextjs-app
igniter dev --cmd "pnpm dev"
```

### Express API Dev Mode

```bash
cd my-express-api
igniter dev --cmd "pnpm dev"
```

### Custom Router and Output Paths

```bash
igniter dev \
  --router ./src/custom/igniter.router.ts \
  --output ./src/generated/igniter.schema.ts \
  --docs-output ./public/openapi \
  --cmd "pnpm dev"
```

### Without a Dev Server (Watch Only)

```bash
# If --cmd is omitted and there's no dev script, the CLI
# runs in watch-only mode — regenerating on file changes
# without a dev server.
igniter dev
```

***

## `generate schema` (Watch Mode)

The `generate schema` command has a programmatic **watch mode** variant used internally by `igniter dev`. It bundles the router using **esbuild** in-memory and extracts the schema without writing files to disk:

```
Router file → esbuild bundle → Router introspection → Schema type extraction → Write output
```

Returns: `{ controllers: number, actions: number, durationMs: number }`

***

## `generate docs` (Watch Mode)

Similarly, `generate docs` has a watch-mode variant that produces OpenAPI output and returns metadata:

```
Router file → esbuild bundle → Router introspection → OpenAPI conversion → Write spec
```

Returns: `{ sizeKb: number, durationMs: number }`

***

## Next Steps

<Cards>
  <Card title="Real-World Scenarios" description="Dev mode in CI/CD, team workflows, and multi-service monorepos." href="/docs/cli/real-world" />

  <Card title="Best Practices" description="Optimize your dev workflow — when to use flags vs. interactive mode." href="/docs/cli/best-practices" />

  <Card title="Troubleshooting" description="Fix common dev mode issues — watcher errors, port conflicts, router errors." href="/docs/cli/troubleshooting" />
</Cards>


---

# generate

> Scaffold features, controllers, procedures, client schema, OpenAPI docs, and typed callers. Schema-aware generation with Prisma support.
URL: https://igniterjs.com/docs/cli/commands/generate

## `igniter generate`

The `generate` command scaffolds code from templates and schemas. It has six subcommands — each focused on a specific code generation task.

```bash
igniter generate <subcommand> [options]
```

***

## Subcommands

| Subcommand   | Description                                                              |
| ------------ | ------------------------------------------------------------------------ |
| `feature`    | Scaffold a complete feature module (controller + procedure + interfaces) |
| `controller` | Scaffold a controller within an existing feature                         |
| `procedure`  | Scaffold a procedure within an existing feature                          |
| `docs`       | Generate an OpenAPI specification from your router                       |
| `schema`     | Generate a TypeScript client schema from your router                     |
| `caller`     | Generate a typed Igniter Caller from an OpenAPI spec                     |

***

## `generate feature`

Creates a complete feature module — controllers, procedures, and interfaces. Can generate from a **Prisma schema model** for schema-aware, type-safe scaffolding.

```bash
igniter generate feature [name] [options]
```

### Options

| Option          | Type     | Description                                                  |
| --------------- | -------- | ------------------------------------------------------------ |
| `[name]`        | `string` | Feature name (kebab-case). If omitted, prompts interactively |
| `--schema`      | `string` | Generate from a schema provider (e.g., `prisma:User`)        |
| `--schema-path` | `string` | Custom path to the schema file                               |

### Schema-Aware Generation

When you pass `--schema prisma:User`, the CLI:

1. Finds the **PrismaSchemaProvider** in the schema provider registry
2. Parses the `prisma:User` option → extracts `modelName = "User"`
3. Validates that the `User` model exists in your Prisma schema
4. Reads column names, types, and relations from the model
5. Generates a controller with Zod-validated CRUD routes
6. Generates procedures with Prisma queries matching your schema
7. Generates interfaces with types derived from the model

```bash
# Schema-aware generation from a Prisma model
igniter generate feature users --schema prisma:User

# With a custom schema file path
igniter generate feature users --schema prisma:User --schema-path ./prisma/custom/schema.prisma
```

### Empty Feature

Without `--schema`, the CLI generates an empty feature skeleton:

```bash
igniter generate feature products
```

This creates:

```
src/features/products/
├── controllers/
│   └── products.controller.ts    ← Empty controller with base scaffold
├── procedures/
│   └── .gitkeep
└── products.interfaces.ts        ← Empty interfaces file
```

### Interactive Mode

When no name is provided, the CLI prompts interactively. If a Prisma schema is detected, it offers to generate from an available model:

```bash
igniter generate feature
# ? Generate from an available schema provider?
#   ○ No, create an empty feature
#   ● Prisma
# ? Which model would you like to scaffold?
#   ● User
#   ○ Post
#   ○ Comment
```

***

## `generate controller`

Scaffolds a controller within an existing feature.

```bash
igniter generate controller [name] [options]
```

### Options

| Option          | Type     | Description                                     |
| --------------- | -------- | ----------------------------------------------- |
| `[name]`        | `string` | Controller name in kebab-case (e.g., `profile`) |
| `-f, --feature` | `string` | Target feature name                             |

```bash
# Scaffold a profile controller inside the users feature
igniter generate controller profile --feature users
```

The generated controller uses the `empty.controller.hbs` template and exports a class with `ControllerDisplayName` and `controllerRoute` derived from the name.

***

## `generate procedure`

Scaffolds a procedure within an existing feature. Removes the `.gitkeep` placeholder from the procedures directory.

```bash
igniter generate procedure [name] [options]
```

### Options

| Option          | Type     | Description                                               |
| --------------- | -------- | --------------------------------------------------------- |
| `[name]`        | `string` | Procedure name in kebab-case (e.g., `send-welcome-email`) |
| `-f, --feature` | `string` | Target feature name                                       |

```bash
# Scaffold a send-welcome-email procedure inside the users feature
igniter generate procedure send-welcome-email --feature users
```

***

## `generate docs`

Generates an OpenAPI 3.x specification from your Igniter router.

```bash
igniter generate docs [options]
```

### Options

| Option     | Type     | Default                 | Description                           |
| ---------- | -------- | ----------------------- | ------------------------------------- |
| `--router` | `string` | `src/igniter.router.ts` | Path to the router file               |
| `--output` | `string` | `./src/docs`            | Output directory for the OpenAPI spec |

```bash
# Default paths
igniter generate docs

# Custom paths
igniter generate docs --router ./custom/igniter.router.ts --output ./public/api-docs
```

***

## `generate schema`

Generates a TypeScript client schema from your Igniter router. This schema provides full type inference for client-side API calls.

```bash
igniter generate schema [options]
```

### Options

| Option     | Type     | Default                 | Description                     |
| ---------- | -------- | ----------------------- | ------------------------------- |
| `--router` | `string` | `src/igniter.router.ts` | Path to the router file         |
| `--output` | `string` | `src/igniter.schema.ts` | Output path for the schema file |

```bash
# Default paths
igniter generate schema

# Custom output
igniter generate schema --output ./src/generated/api.schema.ts
```

***

## `generate caller`

Generates a fully typed, Zod-validated **Igniter Caller** from any OpenAPI 3.x specification. The caller includes typed request methods, Zod schema validation, and automatic response parsing.

```bash
igniter generate caller [options]
```

### Options

| Option     | Type     | Description                                             |
| ---------- | -------- | ------------------------------------------------------- |
| `--name`   | `string` | Name prefix for generated schemas and caller export     |
| `--url`    | `string` | URL to a remote OpenAPI document                        |
| `--path`   | `string` | Local path to an OpenAPI document                       |
| `--output` | `string` | Output directory (defaults to `src/callers/<hostname>`) |

### From a Remote URL

```bash
igniter generate caller --name stripe --url https://api.stripe.com/openapi.json
```

### From a Local File

```bash
igniter generate caller --name internal --path ./openapi.json
```

### Interactive Mode

Without `--url` or `--path`, the CLI prompts:

```bash
igniter generate caller
# ? Caller name (e.g., facebook, billing) stripe
# ? Where is your OpenAPI spec? Remote URL
# ? OpenAPI URL https://api.stripe.com/openapi.json
```

### Generated Output

The command produces two files:

```
src/callers/api.stripe.com/
├── schema.ts    ← Zod schemas for all request/response types
└── index.ts     ← Preconfigured IgniterCaller instance
```

The schema file contains Zod schemas for every component in the OpenAPI spec. The caller file exports a preconfigured `IgniterCaller` with:

* Base URL inferred from the OpenAPI `servers[0].url` or the source URL
* All schemas registered in `strict` mode
* Type-safe method calls for every path

```typescript
// Generated index.ts
import { IgniterCaller } from "@igniter-js/caller";
import { stripeCallerSchemas } from "./schema";

export const stripeCaller = IgniterCaller.create()
  .withBaseUrl("https://api.stripe.com")
  .withSchemas(stripeCallerSchemas, { mode: "strict" })
  .build();
```

<Callout type="warn">
  Only **OpenAPI 3.x** documents are supported. Swagger 2.0 documents must be converted first.
</Callout>

***

## Template Engine

All `generate` subcommands use the **Handlebars template engine**. Templates are resolved from multiple candidate locations:

1. `packages/cli/templates/` (bundled with the CLI)
2. `node_modules/@igniter-js/new-cli/templates/` (installed dependency)
3. `./templates/` (project-local overrides)

### Custom Handlebars Helpers

The CLI registers custom helpers available in all templates:

| Helper                  | Example                                     | Output                  |
| ----------------------- | ------------------------------------------- | ----------------------- |
| `includes`              | `{{#if (includes enabledAddOns "store")}}`  | Boolean check           |
| `isEmpty`               | `{{#if (isEmpty enabledAddOns)}}`           | Empty check             |
| `isDefined`             | `{{#if (isDefined addOnOptions.database)}}` | Defined check           |
| `join`                  | `{{join addOnOptions.auth.plugins ", "}}`   | `"email, passkey, jwt"` |
| `capitalizeSlug`        | `{{capitalizeSlug projectName}}`            | `"My App"`              |
| `get`                   | `{{#if (get addOnOptions "database.orm")}}` | Nested access           |
| `eq`                    | `{{#if (eq starter "nextjs")}}`             | Equality check          |
| `camelCase`             | `{{camelCase "two-factor"}}`                | `"twoFactor"`           |
| `filterPlugins`         | `{{#each (filterPlugins plugins)}}`         | Iterate plugins         |
| `generatePluginImports` | `{{{generatePluginImports plugins}}}`       | Import statements       |

***

## Next Steps

<Cards>
  <Card title="dev" description="Watch mode — auto-regenerate schema and docs as you code." href="/docs/cli/commands/dev" />

  <Card title="Real-World Scenarios" description="Production patterns: generate callers, CI/CD pipelines, and team workflows." href="/docs/cli/real-world" />

  <Card title="API Reference" description="Complete reference for every flag, option, and subcommand." href="/docs/cli/api-reference" />
</Cards>


---

# init

> Create a new Igniter.js project or install into an existing one. Starters, add-ons, inline option notation, and CLI flags — the complete reference.
URL: https://igniterjs.com/docs/cli/commands/init

## `igniter init`

The `init` command is the entry point for every Igniter.js project. It handles project creation, starter selection, add-on configuration, dependency installation, Docker setup, and Git initialization — all in a single command.

```bash
igniter init [project-name] [options]
```

***

## Modes

The CLI supports two modes of operation:

| Mode                      | Trigger                         | Behavior                                                              |
| ------------------------- | ------------------------------- | --------------------------------------------------------------------- |
| **new-project** (default) | `igniter init my-app`           | Creates a new directory with a selected starter, then applies add-ons |
| **install**               | `igniter init . --mode install` | Adds Igniter.js to an existing project without overwriting files      |

<Callout type="info">
  In **install** mode, the CLI auto-detects your framework by checking for `next.config.js`/`next.config.ts` (Next.js) or `@tanstack/react-start` in your `package.json` (TanStack Start). If neither is found, it defaults to `generic`.
</Callout>

***

## Options

| Option                    | Type                                            | Default            | Description                                                  |
| ------------------------- | ----------------------------------------------- | ------------------ | ------------------------------------------------------------ |
| `[project-name]`          | `string`                                        | —                  | Name of the project directory (positional argument)          |
| `--mode`                  | `"install" \| "new-project"`                    | `new-project`      | Whether to create a new project or install into existing     |
| `--pm, --package-manager` | `"npm" \| "yarn" \| "pnpm" \| "bun"`            | auto-detected      | Package manager override                                     |
| `--template`              | `string`                                        | interactive prompt | Starter template to use                                      |
| `--add-ons`               | `string`                                        | —                  | Comma-separated list of add-ons with optional inline options |
| `--database`              | `"none" \| "postgresql" \| "mysql" \| "sqlite"` | —                  | Database provider (shorthand for database add-on)            |
| `--no-git`                | flag                                            | `false`            | Skip Git initialization                                      |
| `--no-install`            | flag                                            | `false`            | Skip automatic dependency installation                       |
| `--no-docker`             | flag                                            | `false`            | Skip Docker Compose setup                                    |

### Available Starters (--template)

| Value              | Name             | Runtime | Type                     |
| ------------------ | ---------------- | ------- | ------------------------ |
| `nextjs`           | Next.js          | Node.js | Full-stack (React + API) |
| `tanstack-start`   | TanStack Start   | Node.js | Full-stack (React + API) |
| `express-rest-api` | Express REST API | Node.js | Backend API              |
| `bun-rest-api`     | Bun REST API     | Bun     | Backend API              |
| `bun-react-app`    | Bun React App    | Bun     | Full-stack (React + API) |
| `deno-rest-api`    | Deno REST API    | Deno    | Backend API              |

### Available Add-ons (--add-ons)

| Value       | Name           | Description                                             |
| ----------- | -------------- | ------------------------------------------------------- |
| `database`  | Database       | Prisma or Drizzle ORM with PostgreSQL, MySQL, or SQLite |
| `auth`      | Authentication | Better Auth with 20+ plugin options                     |
| `jobs`      | Jobs           | Background job processing                               |
| `store`     | Store          | Redis-backed key-value store                            |
| `mcp`       | MCP Server     | Model Context Protocol server for AI agents             |
| `logging`   | Logging        | Structured logging with Pino                            |
| `telemetry` | Telemetry      | OpenTelemetry tracing, metrics, and events              |
| `bots`      | Bots           | Multi-platform bot setup (Telegram, WhatsApp, Discord)  |
| `shadcn-ui` | shadcn/ui      | UI component library initialization                     |

***

## Interactive Mode

When you run `igniter init` without flags, the CLI guides you through an interactive setup:

```bash
igniter init
# ? What will your project be called? my-saas
# ? Which starter would you like to use? Next.js
# ? What add-ons would you like for your project? database, auth
# ? Which ORM? Prisma
# ? Which database provider? PostgreSQL
# ? Which package manager? pnpm
# ? Setup Docker services for development? Yes
# ? Initialize Git repository? Yes
# ? Install dependencies automatically? Yes
```

The CLI auto-detects your current package manager from `npm_config_user_agent` and pre-selects it.

***

## Inline Add-on Options

Add-ons with configurable options support an **inline notation** for non-interactive use:

```
--add-ons "addon-name:option1:option2+value2+value3"
```

### Database Add-on

| Option     | Position | Values                          |
| ---------- | -------- | ------------------------------- |
| `orm`      | 1        | `prisma`, `drizzle`             |
| `provider` | 2        | `postgresql`, `mysql`, `sqlite` |

```bash
# Prisma + PostgreSQL
igniter init app --add-ons "database:prisma:postgresql"

# Drizzle + MySQL
igniter init app --add-ons "database:drizzle:mysql"

# Drizzle + SQLite
igniter init app --add-ons "database:drizzle:sqlite"
```

### Auth Add-on

| Option     | Position | Values                                                                                |
| ---------- | -------- | ------------------------------------------------------------------------------------- |
| `provider` | 1        | `better-auth`                                                                         |
| `plugins`  | 2        | multi-select: `email`, `two-factor`, `username`, `magic-link`, `passkey`, `jwt`, etc. |

```bash
# Better Auth with email + magic link + passkey
igniter init app --add-ons "auth:better-auth:email+magic-link+passkey"

# Better Auth with username + two-factor
igniter init app --add-ons "auth:better-auth:username+two-factor"
```

### Multiple Add-ons Combined

```bash
# SaaS starter: database + auth + jobs + logging
igniter init my-saas \
  --template nextjs \
  --add-ons "database:prisma:postgresql,auth:better-auth:email+passkey,jobs,logging"
```

<Callout type="info">
  Add-ons without options (like `jobs`, `logging`, `store`) just use their ID. Add-ons with options use the `:` separator for positional values and `+` for multi-value selections.
</Callout>

***

## Init Flow (Internal)

When you run `igniter init`, the CLI executes these steps in order:

```
1. Collect prompts
   ├── Project name, starter, add-ons
   ├── Add-on options (ORM, provider, plugins)
   └── Package manager, Docker, Git preferences

2. Create project structure
   └── Clone/apply starter template

3. Apply add-ons (in registration order)
   ├── Dependencies → package.json
   ├── Docker services → docker-compose.yml
   ├── Environment variables → .env
   └── Templates → source files

4. Install dependencies (optional)
   └── npm/pnpm/yarn/bun install

5. Docker setup (optional)
   ├── Stop conflicting containers
   ├── Free occupied ports
   └── docker-compose up -d

6. Git initialization (optional)
   ├── git init
   ├── git add .
   └── git commit -m "Initial commit from Igniter.js CLI"

7. Post-install hooks (add-ons)
   └── Run add-on postInstall scripts (requires deps installed)
```

***

## Examples

### Create a Full-Stack SaaS Project

```bash
igniter init my-saas \
  --template nextjs \
  --add-ons "database:prisma:postgresql,auth:better-auth:email+magic-link+passkey,jobs,logging,telemetry" \
  --pm pnpm
```

### Create a Minimal Backend API

```bash
igniter init my-api \
  --template express-rest-api \
  --add-ons logging \
  --no-docker \
  --no-git
```

### Install into an Existing Next.js Project

```bash
cd my-existing-nextjs-app
igniter init . --mode install --add-ons "database:prisma:postgresql"
```

### Create a Bun Project

```bash
igniter init my-bun-api \
  --template bun-rest-api \
  --add-ons "database:drizzle:sqlite,logging"
```

### Create a Deno Project

```bash
igniter init my-deno-api \
  --template deno-rest-api \
  --add-ons logging,telemetry
```

***

## Package Manager Detection

The CLI detects your package manager from the `npm_config_user_agent` environment variable:

| User Agent Prefix | Detected PM | Executor   |
| ----------------- | ----------- | ---------- |
| `yarn/`           | `yarn`      | `yarn dlx` |
| `pnpm/`           | `pnpm`      | `pnpx`     |
| `bun/`            | `bun`       | `bunx`     |
| (anything else)   | `npm`       | `npx`      |

If `--pm` is passed explicitly, it overrides auto-detection.

***

## Framework Detection (Install Mode)

In `--mode install`, the CLI auto-detects your framework:

| Detection Rule                                         | Framework        |
| ------------------------------------------------------ | ---------------- |
| `next.config.js` or `next.config.ts` exists            | `nextjs`         |
| `@tanstack/react-start` in `package.json` dependencies | `tanstack-start` |
| Neither                                                | `generic`        |

This determines which templates and add-on adapters are used.

***

## Next Steps

<Cards>
  <Card title="generate" description="Scaffold features, controllers, procedures, and generate docs/schema/callers." href="/docs/cli/commands/generate" />

  <Card title="dev" description="Watch mode with automatic schema and OpenAPI regeneration." href="/docs/cli/commands/dev" />

  <Card title="Starters" description="Compare all 6 starters in detail — frameworks, env vars, and templates." href="/docs/cli/starters" />

  <Card title="Add-ons" description="Every add-on documented — options, templates, dependencies, and env vars." href="/docs/cli/add-ons" />
</Cards>


---

# Commands

> Learn how to use slash commands to trigger automated workflows with Lia in your SaaS Boilerplate project.
URL: https://igniterjs.com/docs/core/commands

import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Accordions, Accordion } from 'fumadocs-ui/components/accordion';

By the end of this guide, you'll understand how to use slash commands with Lia to automate development workflows in your SaaS Boilerplate project.

## What Are Commands in Code Agents?

Commands are custom slash commands (like `/setup` or `/create-command`) that trigger specific automated workflows in AI code agents. When you type a slash command in your chat with Lia, she executes a predefined sequence of actions designed to accomplish complex development tasks.

In modern code agents (Cursor, VS Code Copilot, Claude Code, etc.), commands provide a way to create "shortcuts" for frequently used workflows. Instead of describing what you want to do in natural language each time, you can use a command to trigger a specific, well-defined process.

## How Commands Work

When you interact with Lia, she automatically recognizes slash commands and executes the corresponding workflow. These commands influence:

* **Project Setup**: Environment configuration and dependency management
* **Code Generation**: Automated creation of components, pages, and features
* **Quality Assurance**: Testing, validation, and documentation workflows
* **Development Automation**: Streamlined processes for common tasks

## Commands in SaaS Boilerplate

The SaaS Boilerplate includes a comprehensive set of commands organized in the `.rulesync/commands/` directory. These commands are specifically designed for multi-tenant SaaS applications built with modern web technologies.

### File Structure

```
.rulesync/commands/
├── init.md                 # Personalized project onboarding
├── setup.md                # Environment configuration and dependencies
├── create-command.md       # Custom command creation workflow
├── create-rule.md          # Custom rule creation workflow
├── docs.md                 # Documentation generation and management
└── task.md                 # Complete feature development lifecycle
```

### Available Commands

| Command           | Description                                                                      |
| ----------------- | -------------------------------------------------------------------------------- |
| `/init`           | Start personalized project onboarding and setup guidance                         |
| `/setup`          | Guide through complete environment configuration and dependency installation     |
| `/create-command` | Create new custom slash commands with proper structure and validation            |
| `/create-rule`    | Create new rules for training Lia and automating workflows                       |
| `/docs`           | Generate and manage project documentation automatically                          |
| `/task`           | Guide through complete feature development lifecycle from planning to deployment |

## Using Commands

To use a command, simply type it in your chat with Lia:

<Steps>
  <Step>
    ### Start a chat with Lia

    Open your preferred code editor and start a chat with Lia.
  </Step>

  <Step>
    ### Type the slash command

    Enter the command you want to execute:

    ```
    /setup
    ```
  </Step>

  <Step>
    ### Follow the guidance

    Lia will guide you through any required prompts and questions.
  </Step>

  <Step>
    ### Review results

    Once complete, review the generated files, code changes, or other outputs.
  </Step>
</Steps>

## Creating Custom Commands

To create a new custom command for your project, you have two options: using the `/create-command` command for guided creation, or manually creating the command file.

<Tabs items={["Via Command", "Manual Creation"]} defaultIndex={0}>
  <Tab>
    Use the `/create-command` command in your chat with Lia to create a new command interactively.

    <Steps>
      <Step>
        ### Start the command

        In your chat with Lia, type:

        ```
        /create-command
        ```
      </Step>

      <Step>
        ### Define the command details

        Lia will guide you through:

        * **Command name**: The slash command (e.g., `/my-custom-workflow`)
        * **Purpose**: What the command should accomplish
        * **Workflow steps**: The sequence of actions to execute
        * **Validation rules**: How to ensure the command works correctly
      </Step>

      <Step>
        ### Test and finalize

        Lia will create the command file and allow you to test it before finalizing.
      </Step>
    </Steps>
  </Tab>

  <Tab>
    Create the command file manually in the `.rulesync/commands/` directory.

    <Steps>
      <Step>
        ### Create the command file

        Create a new Markdown file in `.rulesync/commands/` with a descriptive name:

        ```bash
        touch .rulesync/commands/my-custom-command.md
        ```
      </Step>

      <Step>
        ### Add the command structure

        Use this template as a starting point:

        ```yaml
        ---
        description: "Custom command for [specific purpose]"
        ---

        # /my-custom-command

        ## Overview
        [Explain what this command does and when to use it]

        ## Workflow Steps
        1. [Step 1 description]
        2. [Step 2 description]
        3. [Additional steps as needed]

        ## Validation
        [How to verify the command worked correctly]

        ## Integration Points
        [How this command works with other commands or rules]
        ```
      </Step>

      <Step>
        ### Customize the command

        Replace the placeholders with your specific requirements:

        * Update the `description` in the frontmatter
        * Define clear workflow steps that Lia can follow
        * Include validation criteria
        * Document integration points with existing commands
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Troubleshooting

<Accordions type="multiple">
  <Accordion title="Command Not Recognized">
    **Problem:** Lia doesn't recognize the slash command you typed.

    **Solution:**

    * Ensure you're in an active chat with Lia in your code editor
    * Check the command syntax (include the `/` at the beginning)
    * Verify the command exists in the table above
    * Make sure you're using the correct command name without typos
  </Accordion>

  <Accordion title="Workflow Issues">
    **Problem:** A command workflow fails or doesn't complete properly.

    **Solution:**

    * Follow Lia's guidance step by step without skipping prompts
    * Answer questions clearly and completely
    * Approve automated actions when prompted
    * Check for error messages and address them
    * Contact support if workflows fail repeatedly
  </Accordion>

  <Accordion title="Command Not Working as Expected">
    **Problem:** The command runs but produces unexpected results.

    **Solution:**

    * Verify you're in the correct project directory
    * Check that all prerequisites are met (dependencies, environment setup)
    * Review the command output for specific error messages
    * Try running the command again after fixing any issues
    * Check the project documentation for command-specific requirements
  </Accordion>
</Accordions>

## Integration with Rules

Commands work seamlessly with rules to provide comprehensive automation:

* **Setup Commands**: Use environment rules for configuration
* **Development Commands**: Apply coding standards and patterns
* **Testing Commands**: Follow validation and quality rules
* **Documentation Commands**: Use documentation standards


---

# Create Rule

> Learn how to use the create-rule command to automate the creation of new rules that guide Lia's behavior and development workflows.
URL: https://igniterjs.com/docs/core/create-rule

By the end of this guide, you'll understand how to use the create-rule command to automate the creation of new rules in your SaaS Boilerplate project, ensuring they integrate seamlessly with workflows and enhance Lia's training context.

## What is the Create Rule Command?

The create-rule command is a specialized automation tool that guides you through creating new rules for the SaaS Boilerplate ecosystem. Rules define standards, protocols, and decision-making frameworks that Lia uses to ensure consistent, high-quality development practices.

This command is particularly useful when you need to:

* Standardize development processes and workflows
* Enhance Lia's training and decision-making capabilities
* Create quality gates and validation protocols
* Establish architectural patterns and best practices

## Before You Begin

### Prerequisites

* Access to the `.rulesync/rules/` directory
* Understanding of the rule ecosystem structure
* Familiarity with the workflows and commands you want to integrate
* Clear understanding of the behavior or process you want to standardize

### Required Context

* Knowledge of existing rules to avoid duplication
* Understanding of when the rule should apply (`alwaysApply` vs contextual)
* Awareness of file patterns and scopes for rule application

## Using the Create Rule Command

<Steps>
  <Step>
    ### Phase 1: Define Your Rule Purpose

    Start by clarifying what your rule should accomplish. The create-rule command will guide you through understanding:

    **For Workflow Automation:**

    * Which processes need standardization?
    * What steps should be automated?
    * What success criteria must be met?
    * How should it integrate with existing workflows?

    **For Training Enhancement:**

    * What behavior should Lia learn?
    * Which decision-making patterns need guidance?
    * How will this improve code quality and consistency?
    * What patterns should be recognized and enforced?

    **For Both (Recommended):**

    * How can the rule enhance both automation and training?
    * What workflows can it reference or trigger?
    * How does it integrate with the broader ecosystem?
  </Step>

  <Step>
    ### Phase 2: Analyze Existing Context

    The command helps you analyze the current ecosystem to ensure proper integration.

    ```bash
    # The create-rule command will automatically:
    # - Search for related rules and workflows
    # - Check existing rule structures
    # - Analyze applicable file patterns
    # - Identify integration opportunities
    ```

    **Key Questions Addressed:**

    * Does this overlap with existing rules?
    * Which workflows should be referenced?
    * How will this enhance Lia's training?
    * What quality gates should be enforced?
  </Step>

  <Step>
    ### Phase 3: Design Rule Structure

    Choose the appropriate rule type and configure metadata based on your needs.

    <Accordions type="multiple">
      <Accordion title="Workflow-Focused Rules">
        Best for standardizing development processes, tool usage patterns, and integration workflows.

        **Examples:**

        * Development process automation
        * Quality assurance protocols
        * Tool usage guidelines
        * Integration standards
      </Accordion>

      <Accordion title="Training-Focused Rules">
        Ideal for enhancing Lia's decision-making, pattern recognition, and knowledge integration.

        **Examples:**

        * Code quality standards
        * Architectural patterns
        * Best practice enforcement
        * Pattern recognition frameworks
      </Accordion>

      <Accordion title="Hybrid Rules (Recommended)">
        Perfect for combining automation with training context for comprehensive development guidance.

        **Examples:**

        * Process automation with decision guidance
        * Quality enforcement with learning
        * Workflow triggers with training context
      </Accordion>
    </Accordions>
  </Step>

  <Step>
    ### Phase 4: Configure Rule Metadata

    Set up the frontmatter that controls how and when the rule applies.

    ```yaml
    ---
    description: "Clear description of what the rule does"
    globs: ["specific files or patterns to apply to"]
    alwaysApply: false  # true for mandatory rules, false for contextual
    ---
    ```

    **Metadata Guidelines:**

    * `description`: Must be clear, actionable, and specific
    * `globs`: Use specific patterns for optimal performance
    * `alwaysApply`: Reserve for critical standards only
  </Step>

  <Step>
    ### Phase 5: Implement and Validate

    The create-rule command generates a properly structured rule file with:

    **Standard Structure:**

    * Clear purpose and overview
    * Core principles and requirements
    * Implementation guidelines
    * Quality gates and validation criteria
    * Integration points and relationships

    **Automatic Validation:**

    * Rule structure verification
    * Conflict detection with existing rules
    * Integration point validation
    * Performance testing
  </Step>

  <Step>
    ### Phase 6: Deploy and Document

    Once created, the rule is automatically:

    * Moved to the correct location in `.rulesync/rules/`
    * Integrated with the memory system
    * Made available for immediate use by Lia
    * Documented for future reference
  </Step>
</Steps>

## Rule Parameters

<TypeTable
  type={{
  purpose: {
    description: 'The primary goal or behavior to standardize',
    type: 'string',
    default: 'Required - must be specified'
  },
  type: {
    description: 'Rule category (workflow/training/hybrid)',
    type: 'string',
    default: 'hybrid'
  },
  scope: {
    description: 'File patterns where the rule applies',
    type: 'array',
    default: '["**/*"]'
  },
  alwaysApply: {
    description: 'Whether the rule applies universally or contextually',
    type: 'boolean',
    default: 'false'
  },
  workflows: {
    description: 'Workflows that this rule can reference or trigger',
    type: 'array',
    default: '[]'
  },
  validate: {
    description: 'Enable automatic validation and testing',
    type: 'boolean',
    default: 'true'
  }
}}
/>

## Usage Examples

### Creating a Workflow Automation Rule

```bash
# Create a rule for development process standardization
/create-rule --purpose "Standardize feature development workflow" --type workflow --scope "src/**/*.{ts,tsx}" --workflows "feature-development,testing-validation" --validate true
```

**What happens:**

1. Analyzes existing development patterns
2. Creates rule structure with workflow integration
3. Defines quality gates and validation steps
4. Generates comprehensive documentation
5. Tests integration with existing workflows

### Creating a Training Enhancement Rule

```bash
# Create a rule for code quality standards
/create-rule --purpose "Enhance TypeScript best practices" --type training --scope "src/**/*.{ts,tsx}" --alwaysApply true --validate true
```

**What happens:**

1. Scans codebase for TypeScript patterns
2. Creates decision-making framework
3. Defines pattern recognition criteria
4. Sets up training context for Lia
5. Generates examples and best practices

### Creating a Hybrid Rule

```bash
# Create a rule for API development standards
/create-rule --purpose "Standardize API development with training context" --type hybrid --scope "src/controllers/**/*.ts" --workflows "api-validation" --validate true
```

**What happens:**

1. Combines automation with training context
2. Defines API development standards
3. Creates validation workflows
4. Provides decision-making guidance
5. Integrates with memory system

## Integration Points

### Workflow Integration

Rules created with this command can reference and trigger workflows:

<Accordions type="multiple">
  <Accordion title="Feature Development Workflow">
    For code generation, scaffolding, and feature implementation processes.
  </Accordion>

  <Accordion title="Testing Validation Workflow">
    For quality assurance, testing protocols, and validation procedures.
  </Accordion>

  <Accordion title="API Validation Workflow">
    For backend API testing, contract validation, and integration testing.
  </Accordion>

  <Accordion title="Deployment Workflow">
    For release processes, environment management, and deployment automation.
  </Accordion>
</Accordions>

### Memory System Enhancement

Every rule created contributes to Lia's knowledge base:

```javascript
// Automatically stores rule patterns
await store_memory({
  type: "architectural_decision",
  title: "Rule-Based Development Standards",
  content: "# Rule Integration Pattern\n\nHow rules guide development decisions...",
  tags: ["rules", "training", "decision-making"],
  confidence: 0.95
});
```

### Cross-Rule Relationships

Rules can reference and build upon each other:

```markdown
## 🔗 Related Rules

This rule relates to:
- `core-principles.mdc` - Fundamental development standards
- `development-workflow.mdc` - Process automation guidelines
- `quality-gates.mdc` - Validation and testing requirements
```

## Quality Gates

The create-rule command enforces several quality standards:

<Accordions type="multiple">
  <Accordion title="Structure Validation">
    Ensures rule follows established format and includes all required sections.
  </Accordion>

  <Accordion title="Integration Testing">
    Validates that the rule works with existing workflows, commands, and tools.
  </Accordion>

  <Accordion title="Performance Validation">
    Tests rule application performance and resource usage.
  </Accordion>

  <Accordion title="Training Context Validation">
    Verifies that the rule provides adequate training context for Lia.
  </Accordion>
</Accordions>

## Troubleshooting

<Accordions type="multiple">
  <Accordion title="Rule Conflicts">
    **Problem:** New rule overlaps with existing functionality.

    **Solution:**

    * Review existing rules in `.rulesync/rules/`
    * Modify scope or purpose to differentiate
    * Consider extending existing rules instead
  </Accordion>

  <Accordion title="Performance Issues">
    **Problem:** Rule application is slow or resource-intensive.

    **Solution:**

    * Narrow file pattern scopes
    * Optimize glob patterns
    * Reduce unnecessary processing
    * Implement caching strategies
  </Accordion>

  <Accordion title="Workflow Integration Problems">
    **Problem:** Rule doesn't trigger workflows correctly.

    **Solution:**

    * Verify workflow file paths and names
    * Check workflow trigger conditions
    * Ensure proper parameter passing
    * Test workflow execution independently
  </Accordion>

  <Accordion title="Training Context Gaps">
    **Problem:** Rule doesn't enhance Lia's decision-making.

    **Solution:**

    * Add more specific examples and patterns
    * Include decision-making frameworks
    * Provide clearer guidance and criteria
    * Test with various scenarios
  </Accordion>
</Accordions>

## Best Practices

### Rule Design

* Keep rules focused on specific, well-defined concerns
* Use clear, actionable language in descriptions and guidelines
* Include comprehensive examples and use cases
* Provide measurable quality gates and validation criteria

### Integration Strategy

* Reference existing rules and workflows when possible
* Contribute meaningful patterns to the memory system
* Ensure rules work well with the task management system
* Document all integration points and relationships clearly

### Performance Considerations

* Use specific file patterns rather than broad globs when possible
* Implement efficient validation logic
* Consider caching for expensive operations
* Test performance with realistic file sets


---

# Meet Lia

> Meet Lia, your specialized AI Code Agent for the Igniter.js ecosystem, designed to accelerate development and maintain high-quality code.
URL: https://igniterjs.com/docs/core/lia-overview

By the end of this guide, you'll understand who Lia is, how she integrates with the Igniter.js to supercharge your development workflow, and how to configure her using our CLI for seamless collaboration.

## Who is Lia?

Lia is an AI Code Agent built specifically for the Igniter.js ecosystem. Unlike generic AI assistants, Lia comes pre-trained with deep knowledge of our framework, including Igniter.js patterns, multi-tenancy architecture, authentication flows, and billing integrations. This specialization makes her incredibly effective at scaffolding features, fixing bugs, and ensuring your code adheres to best practices without the trial-and-error of training a general-purpose agent.

When you create a new project with the Igniter.js CLI, you have the option to configure Lia as your code agent. This replaces the default training of popular agents like GitHub Copilot, Cursor, or Claude Code with our custom setup, ensuring Lia is ready to work with full context of your project from day one.

## Lia's Mission and Core Objectives

Lia's work is guided by three key objectives that make her an indispensable part of building applications:

1. **Accelerate Development**: Lia handles complex tasks autonomously, from feature scaffolding to bug resolution, freeing you to focus on high-level strategy and user experience.

2. **Ensure Quality and Consistency**: As a guardian of your codebase, Lia enforces established patterns, maintains strict type safety, and ensures comprehensive test coverage. She has custom training to keep everything aligned.

3. **Build Persistent Knowledge**: Lia systematically captures and organizes project knowledge—architectural decisions, bug fixes, and implementation details—creating a living documentation system that grows with your project.

## The Birth of Lia: A Natural Evolution

Lia wasn't an afterthought—she emerged as a natural necessity during the development of the Igniter.js. As we built Igniter.js from the ground up as a framework optimized specifically for code agents, we realized that traditional AI assistants couldn't keep up with our innovative patterns and multi-tenant architecture.

Igniter.js was created with AI collaboration in mind, featuring built-in controllers, procedures, and job queues that work seamlessly with automated code generation. But to truly unlock its potential, we needed an AI agent that understood this ecosystem intimately. That's when Lia was born—designed from day one to work in perfect synergy with Igniter.js.

This integrated approach creates something truly unique: a development stack where every component was built to work together. While Igniter.js and Lia are completely open source, they deliver productivity that surpasses any other solution on the market.

### What Lia Can Do For You

Lia is your full-spectrum development collaborator, capable of transforming how you build applications:

**Strategic Planning & Architecture**

* Analyze complex requirements and break them into actionable development tasks
* Consider multi-tenancy implications and scalability from the start
* Propose implementation strategies that leverage Igniter.js patterns optimally

**Code Generation & Implementation**

* Generate production-ready controllers, procedures, and API endpoints
* Create UI components using our Shadcn-based design system
* Implement authentication flows, billing integrations, and business logic
* Write focused, minimal code changes with comprehensive test coverage

**Quality Assurance & Validation**

* Execute unit tests, integration tests, and end-to-end browser testing
* Validate API endpoints and database operations automatically
* Run linters, type checkers, and security scans
* Ensure code adheres to your project's established patterns

**Knowledge Management & Documentation**

* Author comprehensive documentation in our MDX format
* Maintain TSDoc comments and API specifications
* Build and update project knowledge bases as your application evolves
* Generate decision records and architectural documentation

## Collaboration Patterns

Lia works best when collaborating with you in a structured way:

* **Planning Phase**: Lia proposes detailed plans and iterates based on your feedback
* **Implementation**: She creates targeted code changes with tests and documentation
* **Review**: Lia explains her changes and addresses any concerns
* **Validation**: She runs available tests and flags any potential issues

Lia always asks for approval before making destructive changes and never commits secrets or sensitive information.

## Best Practices for Working with Lia

<Accordions type="multiple">
  <Accordion title="Provide Clear Context">
    When asking Lia for help, include relevant file paths, user stories, or acceptance criteria. The more context you provide, the better her suggestions will be.
  </Accordion>

  <Accordion title="Review and Iterate">
    Always review Lia's code changes. While she's designed to follow best practices, your domain expertise is crucial for business logic and user experience decisions.
  </Accordion>

  <Accordion title="Use Tools Appropriately">
    Lia will suggest using MCP tools when relevant, but she always asks for your consent before executing potentially impactful operations.
  </Accordion>

  <Accordion title="Keep Knowledge Updated">
    As your project evolves, Lia helps maintain documentation. Encourage her to update knowledge bases after significant changes.
  </Accordion>
</Accordions>

## Explore More About Lia

<Cards>
  <Card title="Quickstart with Lia" href="./quickstart" description="Get Lia up and running in your local environment or IDE with step-by-step setup guides." />

  <Card title="MCP Servers" href="./mcp-servers" description="Discover the powerful tools Lia uses through Model Context Protocol servers for enhanced capabilities." />

  <Card title="Rules" href="./rules" description="Learn how rules customize Lia's behavior and ensure consistent development practices." />

  <Card title="Commands" href="./commands" description="Master slash commands to trigger automated workflows and accelerate your development process." />
</Cards>

## Troubleshooting

<Accordions type="multiple">
  <Accordion title="Lia not responding in my code agent">
    Ensure you've run the CLI configuration for your specific agent. Check that the agent's configuration files point to the correct project directory.
  </Accordion>

  <Accordion title="MCP tools not working">
    Verify that `.mcp.json` exists in your project root and that the required packages are installed. Some tools may need additional environment variables for authentication.
  </Accordion>

  <Accordion title="Configuration not applying">
    Try the "Sync All Configurations" option in the CLI menu. If issues persist, check for permission problems or conflicting agent configurations.
  </Accordion>
</Accordions>


---

# Igniter.js MCP Server

> Comprehensive guide to configuring and using the Igniter.js Model Context Protocol server for code generation, browser testing, and more.
URL: https://igniterjs.com/docs/core/mcp-servers

By the end of this guide, you'll have a complete understanding of what a Model Context Protocol (MCP) server is, how to configure the Igniter.js MCP server in your favorite IDE or Code Agent, and what tools it provides to enhance your development workflow.

## What is an MCP Server?

A **Model Context Protocol (MCP) Server** is a specialized backend that acts as a bridge between an AI model (like a code agent) and your development environment. It follows a standard protocol that allows the AI to securely access context-aware tools and information that are not part of its general training data.

Think of it as giving your AI assistant a set of superpowers tailored specifically to your project. Instead of just understanding code, it can now:

* Interact with your local development server.
* Run tests and builds.
* Scaffold new features based on your project's conventions.
* Analyze your codebase with deep, contextual understanding.
* Safely access your database or other services.

This allows AI agents like Lia to perform complex, multi-step tasks autonomously, moving beyond simple code completion to become a true pair programmer.

## How to Add the Igniter.js MCP Server

Integrating the Igniter.js MCP Server into your development tool is straightforward. It is typically defined in a JSON configuration file that your IDE or code agent reads on startup.

Below are instructions for popular environments.

<Tabs items={['Cursor', 'VS Code', 'GitHub Copilot', 'Windsurf', 'Trae']}>
  <Tab value="Cursor">
    1. Go to `File` > `Settings` > `Cursor`.
    2. Find the `Model Context Protocol` section.
    3. Click on `Add new global MCP server`.
    4. A `~/.cursor/mcp.json` file will be created if it doesn't exist. Add the following configuration:

    ```json
    {
      "mcpServers": {
        "igniter": {
          "command": "npx",
          "args": ["-y", "@igniter-js/mcp-server@latest"],
          "env": {}
        }
      }
    }
    ```

    5. Save the file and restart Cursor.
  </Tab>

  <Tab value="VS Code">
    1. Create a file named `mcp.json` inside the `.vscode` directory of your project.
    2. Add the following configuration:

    ```json
    {
      "mcpServers": {
        "igniter": {
          "command": "npx",
          "args": ["-y", "@igniter-js/mcp-server@latest"],
          "env": {}
        }
      }
    }
    ```

    3. Save the file and restart VS Code.
  </Tab>

  <Tab value="GitHub Copilot">
    GitHub Copilot in VS Code can also be configured to use MCP servers.

    1. Create a file named `mcp.json` inside the `.vscode` directory of your project.
    2. Add the following configuration:

    ```json
    {
      "mcpServers": {
        "igniter": {
          "command": "npx",
          "args": ["-y", "@igniter-js/mcp-server@latest"],
          "env": {}
        }
      }
    }
    ```

    3. Save the file. Copilot will automatically detect and use the server.
  </Tab>

  <Tab value="Windsurf">
    1. Open Windsurf's settings.
    2. Navigate to the `MCP Servers` configuration section.
    3. Add a new server with the following details:

    ```json
    {
      "mcpServers": {
        "igniter": {
          "command": "npx",
          "args": ["-y", "@igniter-js/mcp-server@latest"],
          "env": {}
        }
      }
    }
    ```

    4. Save and restart Windsurf.
  </Tab>

  <Tab value="Trae">
    1. In Trae, find the option to add a new MCP Server.
    2. Provide the configuration details, which usually involves specifying a command and arguments.

    ```json
    {
      "mcpServers": {
        "igniter": {
          "command": "npx",
          "args": ["-y", "@igniter-js/mcp-server@latest"],
          "env": {}
        }
      }
    }
    ```

    3. Save the configuration.
  </Tab>
</Tabs>

## Igniter.js MCP Server

The Igniter.js MCP server provides comprehensive tools for the complete development lifecycle, including server management, code generation, API testing, documentation, and advanced code analysis capabilities.

### Configuration

The server is started using `npx`. The `-y` flag ensures that `@igniter-js/mcp-server` is automatically downloaded and run without needing a manual installation. The server's behavior can be customized via the following environment variables:

<TypeTable
  type={{
  GITHUB_TOKEN: {
    description: 'Your GitHub Personal Access Token. Required for tools that interact with the GitHub API, such as searching issues or creating pull requests.',
    type: 'string'
  },
  ENABLE_CLI_TOOLS: {
    description: 'Set to "false" to disable tools for interacting with command-line interfaces.',
    type: 'boolean',
    default: 'true'
  },
  ENABLE_API_VALIDATION_TOOLS: {
    description: 'Set to "false" to disable tools for API validation and testing.',
    type: 'boolean',
    default: 'true'
  },
  ENABLE_DOCUMENTATION_TOOLS: {
    description: 'Set to "false" to disable tools related to documentation generation and retrieval.',
    type: 'boolean',
    default: 'true'
  },
  ENABLE_GITHUB_TOOLS: {
    description: 'Set to "false" to disable all GitHub-related tools. Requires GITHUB_TOKEN to be set.',
    type: 'boolean',
    default: 'true'
  },
  ENABLE_FILE_ANALYSIS_TOOLS: {
    description: 'Set to "false" to disable tools for static file analysis.',
    type: 'boolean',
    default: 'true'
  },
  ENABLE_CODE_INVESTIGATION_TOOLS: {
    description: 'Set to "false" to disable tools for deeper code investigation and dependency tracing.',
    type: 'boolean',
    default: 'true'
  },
  ENABLE_DEBUGGING_TOOLS: {
    description: 'Set to "false" to disable debugging-related tools.',
    type: 'boolean',
    default: 'true'
  }
}}
/>

### Available Tools

<Accordions type="multiple">
  <Accordion title="start_dev_server - Start development server">
    This tool starts the Igniter.js development server, a crucial first step for most local development workflows. Lia uses this command at the beginning of a session to run the project, which enables her to test changes in real-time, validate API endpoints, and ensure the application is running correctly. For Lia, having the dev server running provides an immediate feedback loop through hot-reloading and allows her to directly interact with the live application as she builds and modifies features.

    **Parameters**

    <TypeTable
      type={{
  port: {
    description: "Port to run the server on. Defaults to the project's standard port (e.g., 3000).",
    type: 'number'
  },
  watch: {
    description: "Enable file watching for automatic restarts and client regeneration. Defaults to true.",
    type: 'boolean',
    default: 'true'
  }
}}
    />
  </Accordion>

  <Accordion title="build_project - Build for production">
    This tool compiles the entire project for a production environment. Lia uses this to verify that all code, dependencies, and assets are correctly bundled and optimized, catching potential issues that might only appear in a production build. Running a build is a critical quality assurance step before deploying changes, and it gives Lia confidence that the features she has worked on are ready for release.

    **Parameters**

    <TypeTable
      type={{
  mode: {
    description: "Build mode. 'production' is the default and standard for builds.",
    type: "'development' | 'production'",
    default: "'production'"
  }
}}
    />
  </Accordion>

  <Accordion title="run_tests - Execute test suite">
    This tool executes the project's test suite to validate code quality and functionality. After making changes, Lia runs this command to ensure that her modifications work as expected and have not introduced any regressions in other parts of the application. It is a fundamental tool for maintaining a healthy and reliable codebase, allowing her to autonomously verify her work against the project's established standards.

    **Parameters**

    <TypeTable
      type={{
  filter: {
    description: "Filter tests by a specific pattern or package name (e.g., '@igniter-js/core').",
    type: 'string'
  },
  watch: {
    description: "Run tests in watch mode to automatically re-run on file changes.",
    type: 'boolean'
  }
}}
    />
  </Accordion>

  <Accordion title="generate_feature - Create new feature">
    This tool scaffolds a new feature module following Igniter.js conventions, creating the necessary directory structure and boilerplate files. Lia uses this to quickly set up the foundation for a new area of functionality, such as 'user-management' or 'billing'. This automates the repetitive setup process, ensuring consistency across the codebase and allowing Lia to immediately start implementing the specific business logic for the new feature.

    **Parameters**

    <TypeTable
      type={{
  name: {
    description: "The name of the feature in kebab-case (e.g., 'user-management').",
    type: 'string'
  },
  schema: {
    description: "EXPERIMENTAL: Generate CRUD operations from a schema provider (e.g., 'prisma:User').",
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="add_package_dependency - Add Package Dependency">
    This tool adds a new dependency to the project using the configured package manager. When a task requires a new library or package, Lia uses this command to add it to the project's `package.json` and install it. This ensures that all dependencies are managed cleanly and consistently through a single interface, avoiding manual edits to package files.

    **Parameters**

    <TypeTable
      type={{
  package_name: {
    description: "The name of the package to add (e.g., axios, lodash).",
    type: 'string'
  },
  version: {
    description: "The specific version of the package (e.g., ^1.0.0, latest). Defaults to the latest version.",
    type: 'string',
    default: 'null'
  },
  dev_dependency: {
    description: "If true, adds as a development dependency.",
    type: 'boolean',
    default: 'false'
  }
}}
    />
  </Accordion>

  <Accordion title="remove_package_dependency - Remove Package Dependency">
    This tool removes an existing dependency from the project. If a package is no longer needed or is being replaced, Lia can use this command to cleanly uninstall it and remove it from the `package.json`. This helps in keeping the project's dependency tree lean and free of unused packages.

    **Parameters**

    <TypeTable
      type={{
  package_name: {
    description: "The name of the package to remove.",
    type: 'string'
  }
}}
    />
  </Accordion>

  <Accordion title="get_openapi_spec - Retrieve OpenAPI specification">
    This tool retrieves the OpenAPI specification from a running server. Lia uses this to understand the available API endpoints, their expected inputs, and their outputs. This self-discovery mechanism is crucial for her to validate API contracts, test endpoints using `make_api_request`, or even generate client-side code that correctly interacts with the backend.

    **Parameters**

    <TypeTable
      type={{
  url: {
    description: 'API documentation URL',
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="make_api_request - Execute HTTP requests">
    This tool allows for the execution of HTTP requests against any URL, which is essential for API testing and validation. After building a new endpoint or making changes, Lia uses this tool to send requests and inspect the responses, verifying that the API behaves as expected. This enables her to perform autonomous end-to-end testing of the backend services she develops.

    **Parameters**

    <TypeTable
      type={{
  method: {
    description: 'HTTP method',
    type: '"GET"|"POST"|"PUT"|"DELETE"|"PATCH"'
  },
  url: {
    description: 'Request URL',
    type: 'string'
  },
  headers: {
    description: 'Request headers',
    type: 'Record<string,string>',
    default: 'null'
  },
  body: {
    description: 'Request body',
    type: 'any',
    default: 'null'
  },
  timeout: {
    description: 'Request timeout in milliseconds',
    type: 'number',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="read_as_markdown - Fetch external documentation">
    This tool fetches content from a URL and converts it to clean, readable Markdown. Lia uses this for research when she needs to understand a concept, learn about a library, or consult external documentation to solve a problem. It gives her the ability to "read the docs" just like a human developer would, integrating external knowledge into her development process.

    **Parameters**

    <TypeTable
      type={{
  url: {
    description: 'Custom URL for documentation',
    type: 'string'
  }
}}
    />
  </Accordion>

  <Accordion title="analyze_file - Comprehensive file analysis">
    This tool performs a deep analysis of a single source file, providing information about its structure, imports, exports, functions, and any TypeScript or ESLint errors. Lia uses this to understand a file's responsibilities and health before making changes. This analysis helps her identify potential issues, understand dependencies, and plan her modifications with full context.

    **Parameters**

    <TypeTable
      type={{
  filePath: {
    description: 'Path to the file to analyze',
    type: 'string'
  },
  includeErrors: {
    description: 'Include error analysis',
    type: 'boolean',
    default: 'true'
  },
  projectRoot: {
    description: 'Project root directory',
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="analyze_feature - Feature analysis">
    This tool provides a comprehensive analysis of an entire feature module, including its file structure, overall health, and exposed API endpoints. When tasked with working on an existing feature, Lia uses this to get a high-level overview of its components and current state. This allows her to understand the feature's architecture before diving into individual files.

    **Parameters**

    <TypeTable
      type={{
  featurePath: {
    description: 'Path to the feature directory',
    type: 'string'
  },
  projectRoot: {
    description: 'Project root directory',
    type: 'string',
    default: 'null'
  },
  includeStats: {
    description: 'Include statistical analysis',
    type: 'boolean',
    default: 'false'
  }
}}
    />
  </Accordion>

  <Accordion title="find_implementation - Locate symbol definitions">
    This tool helps locate the definition of a specific symbol (like a function, class, or type) within the codebase. When Lia encounters a piece of code she doesn't immediately understand, she uses this tool to trace it back to its source. This "go to definition" capability is fundamental for navigating and understanding large, complex codebases.

    **Parameters**

    <TypeTable
      type={{
  symbol: {
    description: 'Symbol to find',
    type: 'string'
  },
  filePath: {
    description: 'Starting file path',
    type: 'string'
  },
  projectRoot: {
    description: 'Project root directory',
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="explore_source - Deep file analysis">
    This tool performs a deep analysis of a source file, focusing on a specific symbol and its dependencies. It's a more focused version of `analyze_file`. Lia uses it when she needs to understand the implementation details of a particular function or class in depth, providing her with the context needed to make precise and safe code modifications.

    **Parameters**

    <TypeTable
      type={{
  filePath: {
    description: 'Path to the file to explore',
    type: 'string'
  },
  symbol: {
    description: 'Specific symbol to analyze',
    type: 'string',
    default: 'null'
  },
  includeContext: {
    description: 'Include surrounding context',
    type: 'boolean',
    default: 'false'
  }
}}
    />
  </Accordion>

  <Accordion title="trace_dependency_chain - Map import chains">
    This tool maps the complete import chain for a symbol, showing how different parts of the codebase are connected. Lia uses this to understand the impact of a potential change. By tracing dependencies, she can identify which other files or features might be affected by her modifications, preventing unintended side effects and breaking changes.

    **Parameters**

    <TypeTable
      type={{
  symbol: {
    description: 'Symbol to trace',
    type: 'string'
  },
  startFile: {
    description: 'Starting file for tracing',
    type: 'string'
  },
  maxDepth: {
    description: 'Maximum tracing depth',
    type: 'number',
    default: '5'
  }
}}
    />
  </Accordion>

  <Accordion title="get_process_info - Get Process Information">
    This tool provides detailed information about a running process on the system using its Process ID (PID). Lia uses this for debugging purposes, for example, to check if a development server or another required process is running correctly, what port it's using, or how much memory it's consuming. It gives her visibility into the runtime environment.

    **Parameters**

    <TypeTable
      type={{
  process_id: {
    description: 'The PID of the process.',
    type: 'number'
  }
}}
    />
  </Accordion>

  <Accordion title="inspect_runtime_variable - Inspect Runtime Variable">
    This tool allows Lia to inspect the value of a variable in a running JavaScript/TypeScript process that has been started with the `--inspect` flag. This is an incredibly powerful debugging tool, giving her the ability to check the state of the application at runtime without having to add `console.log` statements and restart the server.

    **Parameters**

    <TypeTable
      type={{
  process_id: {
    description: 'The PID of the JavaScript/TypeScript process to inspect.',
    type: 'number'
  },
  variable_name: {
    description: 'The name of the variable to inspect (must be in an accessible scope, preferably global).',
    type: 'string'
  },
  debug_port: {
    description: 'The port where the debugger is listening. Defaults to 9229.',
    type: 'number',
    default: '9229'
  },
  file_path: {
    description: 'The path of the file where the variable is declared.',
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="list_processes_on_port - List Processes on Port">
    This tool lists all processes that are currently listening on a specific network port. Lia uses this to troubleshoot issues like a port already being in use when trying to start a development server. It helps her diagnose and resolve common environment setup problems autonomously.

    **Parameters**

    <TypeTable
      type={{
  port: {
    description: 'The TCP/UDP port to inspect (e.g., 3000, 9230).',
    type: 'number'
  },
  protocol: {
    description: "Filter by protocol. If not provided, searches for both.",
    type: "'tcp' | 'udp'",
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="search_github_issues - Search GitHub issues">
    This tool allows Lia to search for issues and pull requests on GitHub, scoped to the Igniter.js repository by default. She uses this for research, to check if a bug has already been reported, find context on a feature request, or learn from previous solutions. It connects her directly to the project's development history and community discussions.

    **Parameters**

    <TypeTable
      type={{
  query: {
    description: 'Search query',
    type: 'string'
  },
  repository: {
    description: "Target repository in format 'owner/repo'. Defaults to 'felipebarcelospro/igniter-js'",
    type: 'string',
    default: 'null'
  },
  state: {
    description: 'Issue state',
    type: '"open"|"closed"|"all"',
    default: '"open"'
  },
  labels: {
    description: 'Issue labels',
    type: 'string[]',
    default: 'null'
  },
  sort: {
    description: 'Sort order',
    type: '"created"|"updated"|"comments"',
    default: '"created"'
  },
  order: {
    description: 'Sort direction',
    type: '"asc"|"desc"',
    default: '"desc"'
  },
  per_page: {
    description: 'Results per page',
    type: 'number',
    default: '30'
  }
}}
    />
  </Accordion>

  <Accordion title="create_github_issue - Create GitHub issue">
    This tool enables Lia to create new issues on GitHub. If she identifies a bug, has a suggestion for a new feature, or finds a gap in the documentation during her work, she can use this tool to formally report it. This capability allows her to contribute to the project's backlog and participate in the development process just like a human team member.

    **Parameters**

    <TypeTable
      type={{
  title: {
    description: 'Issue title',
    type: 'string'
  },
  body: {
    description: 'Issue description',
    type: 'string'
  },
  repository: {
    description: "Target repository in format 'owner/repo'. Defaults to 'felipebarcelospro/igniter-js'",
    type: 'string',
    default: 'null'
  },
  labels: {
    description: 'Issue labels',
    type: 'string[]',
    default: 'null'
  },
  assignees: {
    description: 'Issue assignees',
    type: 'string[]',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="get_github_issue - Get GitHub Issue Details">
    This tool gives Lia the ability to retrieve detailed information about a specific GitHub issue. She uses this to get the full context of a bug report or feature request, including the description, comments, labels, and current status. This is essential for her to understand the problem thoroughly before starting to work on a solution.

    **Parameters**

    <TypeTable
      type={{
  issueNumber: {
    description: 'The issue number to get details for',
    type: 'number'
  },
  repository: {
    description: "Repository in format 'owner/repo'. Defaults to 'felipebarcelospro/igniter-js'",
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="search_github_code - Search GitHub Code">
    This tool allows Lia to search for code snippets across GitHub repositories. She uses this to find examples of how a particular library is used, learn from existing implementations, or discover solutions to common programming problems. It's a powerful research tool that extends her knowledge beyond the current project's codebase.

    **Parameters**

    <TypeTable
      type={{
  query: {
    description: 'Code search query',
    type: 'string'
  },
  repository: {
    description: "Repository in format 'owner/repo'. If not specified, searches across GitHub",
    type: 'string',
    default: 'null'
  },
  language: {
    description: 'Programming language filter (typescript, javascript, etc.)',
    type: 'string',
    default: 'null'
  },
  filename: {
    description: 'Filename pattern to search in',
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="read_github_file - Read GitHub File">
    This tool gives Lia the ability to read the content of a specific file directly from a GitHub repository. This is useful when she needs to inspect a file from an external project for reference, or to read a file from the project's own repository without having to clone it locally. It provides direct access to source code for analysis and learning.

    **Parameters**

    <TypeTable
      type={{
  repository: {
    description: "The repository in format 'owner/repo'.",
    type: 'string'
  },
  path: {
    description: 'The path to the file within the repository (e.g., src/main.ts).',
    type: 'string'
  },
  ref: {
    description: "The branch, tag, or commit SHA. Defaults to the repository's default branch if not provided.",
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="list_github_repository_content - List GitHub Repository Content">
    This tool allows Lia to list the contents of a directory within a GitHub repository. She uses this to explore the structure of a project, discover files, and navigate the codebase without having it locally. It's a fundamental capability for understanding the layout and organization of an external or remote repository.

    **Parameters**

    <TypeTable
      type={{
  repository: {
    description: "The repository in format 'owner/repo'.",
    type: 'string'
  },
  path: {
    description: 'The path to the directory. Defaults to the root if not provided.',
    type: 'string',
    default: 'null'
  },
  ref: {
    description: "The branch, tag, or commit SHA. Defaults to the repository's default branch.",
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="update_github_issue - Update GitHub Issue">
    This tool allows Lia to modify existing GitHub issues. She can use this to update an issue's title, add details to the body, assign labels, or change its state (e.g., from 'open' to 'closed'). This enables her to manage the lifecycle of issues she is working on, keeping the project board up-to-date with her progress.

    **Parameters**

    <TypeTable
      type={{
  issueNumber: {
    description: 'The issue number to update',
    type: 'number'
  },
  repository: {
    description: "Repository in format 'owner/repo'. Defaults to 'felipebarcelospro/igniter-js'",
    type: 'string',
    default: 'null'
  },
  title: {
    description: 'New title for the issue',
    type: 'string',
    default: 'null'
  },
  body: {
    description: 'New body/description for the issue',
    type: 'string',
    default: 'null'
  },
  labels: {
    description: 'Labels to set on the issue',
    type: 'string[]',
    default: 'null'
  },
  assignees: {
    description: 'Users to assign to the issue',
    type: 'string[]',
    default: 'null'
  },
  state: {
    description: 'New state for the issue',
    type: '"open" | "closed"',
    default: 'null'
  },
  milestone: {
    description: 'Milestone number to associate with the issue',
    type: 'number',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="close_github_issue - Close GitHub Issue">
    This tool provides a straightforward way for Lia to close a GitHub issue. When she has completed a task and verified the fix, she can use this command to mark the corresponding issue as 'closed'. This is a key part of her workflow, allowing her to signal the completion of her work on the project's issue tracker.

    **Parameters**

    <TypeTable
      type={{
  issueNumber: {
    description: 'The issue number to close',
    type: 'number'
  },
  repository: {
    description: "Repository in format 'owner/repo'. Defaults to 'felipebarcelospro/igniter-js'",
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="list_github_issue_comments - List GitHub Issue Comments">
    This tool lets Lia retrieve all the comments from a specific GitHub issue. She uses this to understand the full conversation around a bug or feature, gathering context from the discussion that might not be in the main issue description. This helps her make more informed decisions based on the team's input.

    **Parameters**

    <TypeTable
      type={{
  issueNumber: {
    description: 'The issue number to get comments for',
    type: 'number'
  },
  repository: {
    description: "Repository in format 'owner/repo'. Defaults to 'felipebarcelospro/igniter-js'",
    type: 'string',
    default: 'null'
  },
  per_page: {
    description: 'Number of comments per page (max 100)',
    type: 'number',
    default: 'null'
  },
  page: {
    description: 'Page number for pagination',
    type: 'number',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="create_github_issue_comment - Create GitHub Issue Comment">
    This tool allows Lia to add comments to a GitHub issue. She uses this to ask clarifying questions, provide status updates on her progress, or explain the solution she has implemented. It's her primary way of communicating and collaborating with the human team members on the project's issue tracker.

    **Parameters**

    <TypeTable
      type={{
  issueNumber: {
    description: 'The issue number to comment on',
    type: 'number'
  },
  body: {
    description: 'The comment body',
    type: 'string'
  },
  repository: {
    description: "Repository in format 'owner/repo'. Defaults to 'felipebarcelospro/igniter-js'",
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="update_github_issue_comment - Update GitHub Issue Comment">
    This tool gives Lia the ability to edit one of her existing comments on a GitHub issue. She might use this to correct a mistake, add more information, or clarify a previous update. This ensures her communication remains accurate and clear.

    **Parameters**

    <TypeTable
      type={{
  commentId: {
    description: 'The comment ID to update',
    type: 'number'
  },
  body: {
    description: 'The new comment body',
    type: 'string'
  },
  repository: {
    description: "Repository in format 'owner/repo'. Defaults to 'felipebarcelospro/igniter-js'",
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>

  <Accordion title="delete_github_issue_comment - Delete GitHub Issue Comment">
    This tool allows Lia to delete one of her own comments. She would use this rarely, perhaps if a comment was posted by mistake or contains incorrect information that is better removed than corrected.

    **Parameters**

    <TypeTable
      type={{
  commentId: {
    description: 'The comment ID to delete',
    type: 'number'
  },
  repository: {
    description: "Repository in format 'owner/repo'. Defaults to 'felipebarcelospro/igniter-js'",
    type: 'string',
    default: 'null'
  }
}}
    />
  </Accordion>
</Accordions>

## Best Practices

<Accordions type="multiple">
  <Accordion title="Security Considerations">
    * Never hardcode database credentials or API keys in configuration files.
    * Use environment variables for sensitive configuration.
    * Limit permissions to read-only where possible for development.
  </Accordion>

  <Accordion title="Performance Optimization">
    * Configure appropriate timeouts for long-running operations.
    * Cache frequently accessed schema information or documentation.
  </Accordion>

  <Accordion title="Error Handling">
    * Implement retry logic for transient failures.
    * Log errors for debugging while avoiding sensitive data exposure.
    * Provide meaningful error messages to users.
  </Accordion>

  <Accordion title="Integration with Lia">
    * Lia automatically discovers and uses available MCP tools.
    * Lia will request permission before executing destructive operations.
    * Combine multiple tools for complex workflows (e.g., generate code + run tests).
  </Accordion>
</Accordions>

## Troubleshooting

<Accordions type="multiple">
  <Accordion title="Server Won't Start">
    * Check that all required packages are installed (`npx` should handle this, but network issues can occur).
    * Verify environment variables are set correctly if needed by any tool.
    * Ensure no other process is using the same port if the server requires one.
  </Accordion>

  <Accordion title="Tool Execution Fails">
    * Validate input parameters match tool specifications.
    * Check for permission issues (file system, network).
    * Review error logs for detailed failure information.
  </Accordion>

  <Accordion title="Performance Issues">
    * Adjust timeout values for slow operations.
    * Optimize queries and reduce data transfer for tools that interact with external services.
    * Consider caching for frequently accessed data.
  </Accordion>
</Accordions>


---

# Quickstart with Lia

> Get Lia up and running in your local environment or IDE with step-by-step setup guides.
URL: https://igniterjs.com/docs/core/quickstart

By the end of this guide, you'll have Lia configured and ready to work in your preferred development environment.

## Configuring Lia with the CLI

The easiest way to set up Lia is through the Igniter.js CLI. Even after initial project creation, you can configure or update Lia at any time.

<Card title="Step-by-step">
  <Steps>
    <Step>
      ### Run the Lia configuration command

      ```bash
      npx @igniter-js/cli@latest lia
      ```

      This launches an interactive menu for managing Lia configurations.
    </Step>

    <Step>
      ### Choose your action

      The main menu offers several options:

      * **Initialize LIA on my Code Agents**: Set up Lia for your preferred development tools
      * **Sync All Configurations**: Update all AI code agent settings across your environment
      * **Update .gitignore**: Add Lia-specific patterns to your .gitignore file
      * **Exit**: Close the menu
    </Step>

    <Step>
      ### Configure code agents (if selected)

      When initializing Lia, you'll see a multi-select list of supported code agents:

      * GitHub Copilot
      * Cursor
      * Claude Code
      * Codex CLI
      * Gemini CLI
      * OpenCode
      * Cline
      * Roo Code
      * Qwen Code
      * Kiro IDE
      * Amazon Q Developer CLI
      * JetBrains Junie
      * AugmentCode
      * Windsurf
      * Warp

      Select all the agents you use, then confirm to apply the configuration. This replaces their default training with Lia's specialized setup for the Igniter.js ecosystem.
    </Step>

    <Step>
      ### Verify the setup

      After configuration, Lia will be ready to work in your chosen agents. Test her by asking for help with a simple task, like creating a new page or controller.
    </Step>
  </Steps>
</Card>

## Troubleshooting

<Accordions type="multiple">
  <Accordion title="Lia not responding in my code agent">
    **Problem:** Lia doesn't respond in your configured code agent.

    **Solution:**

    * Ensure you've run the CLI configuration for your specific agent
    * Check that the agent's configuration files point to the correct project directory
    * Verify that the project has the required `.mcp.json` and rule files
  </Accordion>

  <Accordion title="Configuration not applying">
    **Problem:** Changes to Lia's configuration aren't taking effect.

    **Solution:**

    * Try the "Sync All Configurations" option in the CLI menu
    * Check for permission problems or conflicting agent configurations
    * Restart your code agent after configuration changes
  </Accordion>

  <Accordion title="MCP tools not working">
    **Problem:** Lia can't access MCP server tools.

    **Solution:**

    * Verify that `.mcp.json` exists in your project root
    * Ensure all required packages are installed
    * Check for additional environment variables needed for authentication
  </Accordion>
</Accordions>


---

# Rules

> Learn how to use rules to customize Lia's behavior and ensure consistent development practices in your SaaS Boilerplate project.
URL: https://igniterjs.com/docs/core/rules

By the end of this guide, you'll understand how rules work in modern code agents and how to use them to customize Lia's behavior for your Igniter.js project.

## What Are Rules in Code Agents?

Rules are configuration files that customize how AI code agents like Lia behave in your project. They define coding standards, development patterns, tool usage guidelines, and behavioral constraints that ensure consistent, high-quality development practices.

In modern code agents (Cursor, VS Code Copilot, Claude Code, etc.), rules serve as a "training context" that guides the AI's decision-making process. Instead of relying only on the AI's general training data, rules provide project-specific knowledge and constraints.

## How Rules Work in Code Agents

When you interact with Lia, she automatically loads and applies relevant rules from your project. These rules influence:

* **Code Generation**: What patterns and conventions to follow
* **Tool Selection**: Which tools to use for specific tasks
* **Quality Standards**: What constitutes acceptable code quality
* **Behavioral Guidelines**: How to approach problem-solving
* **Project Context**: Understanding your specific requirements and constraints

## Rules in Igniter.js

The Igniter.js includes a comprehensive set of rules organized in the `.rulesync/rules/` directory. These rules are specifically designed for multi-tenant SaaS applications built with modern web technologies.

### File Structure

```
.rulesync/rules/
├── auth.md                 # Authentication and authorization patterns
├── billing.md              # Billing and subscription management
├── browser.md              # Browser automation protocols
├── data-table.md           # Data table component usage
├── delegation.md           # Task delegation protocols
├── docs.md                 # Documentation standards
├── email.md                # Email template creation
├── form.md                 # Form building patterns
├── frontend.md             # Frontend development workflow
├── igniter-advanced-features.md # Advanced Igniter.js features
├── igniter-client.md       # Igniter.js client usage
├── igniter-controllers.md  # Controller development patterns
├── igniter-patterns.md     # Igniter.js development standards
├── igniter-procedures.md   # Procedure creation guidelines
├── notifications.md        # Notification system usage
├── og-image.md             # Dynamic OG image generation
├── overview.md             # Project overview and context
├── page.md                 # Page creation guidelines
├── plugin-manager.md       # Plugin manager usage
├── seo.md                  # SEO component usage
├── testing.md              # API testing and validation
└── tools.md                # Custom tools usage
```

### Rule File Format

Each rule file follows a consistent Markdown format with frontmatter:

```yaml
---
description: "Brief description of the rule's purpose"
targets: ["file patterns or scopes this rule applies to"]
globs: ["**/*"]  # File patterns to match
---
# Rule Title

Rule content with detailed guidelines, protocols, and examples...
```

### Creating Custom Rules

To create a new custom rule for your project, you have two options: using the `/create-rule` command for guided creation, or manually creating the rule file. After creating the rule, you'll need to synchronize it with your code agent using the Igniter.js CLI.

<Tabs items={["Via Command", "Manual Creation"]} defaultIndex={0}>
  <Tab>
    Use the `/create-rule` command in your chat with Lia to create a new rule interactively.

    <Steps>
      <Step>
        ### Start the command

        In your chat with Lia, type:

        ```
        /create-rule
        ```
      </Step>

      <Step>
        ### Follow the prompts

        Lia will guide you through creating the rule:

        * **Rule name**: A descriptive name for your rule
        * **Purpose**: What the rule should accomplish
        * **Target files**: Which file patterns the rule should apply to
        * **Guidelines**: Specific instructions for Lia to follow
      </Step>

      <Step>
        ### Review and approve

        Lia will show you the generated rule file and ask for your approval before creating it.
      </Step>

      <Step>
        ### Sincronize new rule with your code agent

        Use the `--targets` flag to specify which code agents you want to configure:

        ```bash
        npx @igniter-js/cli@latest lia generate --targets copilot,cursor,claudecode
        ```

        Available targets: `copilot`, `cursor`, `claudecode`.
      </Step>

      <Step>
        ### Verify synchronization

        The CLI will confirm successful synchronization for each specified agent. Your new rule is now active and will be applied in future interactions with Lia. **Just start a new session and observe the changes.**
      </Step>
    </Steps>
  </Tab>

  <Tab>
    Create the rule file manually in the `.rulesync/rules/` directory.

    <Steps>
      <Step>
        ### Create the rule file

        Create a new Markdown file in `.rulesync/rules/` with a descriptive name:

        ```bash
        touch .rulesync/rules/my-custom-rule.md
        ```
      </Step>

      <Step>
        ### Add the frontmatter and content

        Use this template as a starting point:

        ```yaml
        ---
        description: "Custom rule for [specific purpose]"
        targets: ["file patterns or scopes"]
        globs: ["**/*.{ts,tsx}"]
        ---

        # Custom Rule Title

        ## Overview
        [Explain what this rule does and why it's needed]

        ## Guidelines
        [Specific instructions for Lia to follow]

        ## Examples
        [Code examples showing the rule in action]

        ## Integration Points
        [How this rule works with other rules or tools]
        ```
      </Step>

      <Step>
        ### Customize the rule

        Replace the placeholders with your specific requirements:

        * Update the `description`, `targets`, and `globs` in the frontmatter
        * Write clear guidelines that Lia can follow
        * Include practical examples from your codebase
        * Document how this rule integrates with existing ones
      </Step>

      <Step>
        ### Sincronize new rule with your code agent

        Use the `--targets` flag to specify which code agents you want to configure:

        ```bash
        npx @igniter-js/cli@latest lia generate --targets copilot,cursor,claudecode
        ```

        Available targets: `copilot`, `cursor`, `claudecode`.
      </Step>

      <Step>
        ### Verify synchronization

        The CLI will confirm successful synchronization for each specified agent. Your new rule is now active and will be applied in future interactions with Lia. **Just start a new session and observe the changes.**
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Troubleshooting

<Accordions type="multiple">
  <Accordion title="Rule Not Applied">
    **Problem:** Lia isn't following a specific rule.

    **Solution:**

    * Check if the rule file exists in `.rulesync/rules/`
    * Verify the glob patterns match your files
    * Ensure the rule syntax is correct
    * Check for conflicting rules
  </Accordion>

  <Accordion title="Rule Conflicts">
    **Problem:** Multiple rules provide conflicting guidance.

    **Solution:**

    * Review rule specificity and scope
    * Reorganize rules to avoid overlap
    * Document conflict resolution decisions
    * Consider merging related rules
  </Accordion>

  <Accordion title="Performance Issues">
    **Problem:** Rules slow down Lia's responses.

    **Solution:**

    * Narrow glob patterns to specific file types
    * Reduce the number of active rules
    * Optimize rule evaluation logic
    * Cache frequently used rule lookups
  </Accordion>
</Accordions>

## Integration with Commands

Rules work seamlessly with slash commands to provide comprehensive automation:

* **Setup Commands**: Use environment rules for configuration
* **Development Commands**: Apply coding standards and patterns
* **Testing Commands**: Follow validation and quality rules
* **Documentation Commands**: Use documentation standards


---

# Using llms.txt

> Learn how the llms.txt standard helps AI agents discover and understand your documentation structure for better results.
URL: https://igniterjs.com/docs/core/using-llms-txt

By the end of this guide, you'll understand how the llms.txt standard works and how Igniter.js leverages it to make documentation more accessible to AI agents like Lia.

## What is llms.txt?

The `llms.txt` standard is a simple convention that helps Large Language Models (LLMs) and AI agents better understand and navigate documentation websites. It's essentially a plain text file that provides a structured overview of your documentation, making it easier for AI tools to:

* **Discover content**: Quickly find relevant documentation pages
* **Understand structure**: See how your docs are organized
* **Get context**: Access high-level information about your project
* **Navigate efficiently**: Jump to specific sections without crawling the entire site

This standard was popularized by libraries like Next.js and has become a common practice across the developer ecosystem.

## How llms.txt Works

The `llms.txt` file is typically placed at the root of your website (e.g., `yoursite.com/llms.txt`) and follows a simple format:

```
# Project Name

Brief description of what this project does.

## Getting Started

- [Quick Start Guide](link-to-quickstart)
- [Installation](link-to-installation)
- [Configuration](link-to-config)

## Core Concepts

- [Architecture Overview](link-to-architecture)
- [API Reference](link-to-api)
- [Best Practices](link-to-best-practices)

## Advanced Topics

- [Performance Tuning](link-to-performance)
- [Troubleshooting](link-to-troubleshooting)
- [Contributing](link-to-contributing)
```

This structured format allows AI agents to quickly understand your project's scope and find the information they need.

## Igniter.js Implementation

Igniter.js comes with `llms.txt` support built-in, making all your content (documentation, blog posts, help center, and updates) easily accessible to AI agents.

### Automatic Content Exposure

Your Igniter.js automatically exposes content through API routes configured in `next.config.ts`:

```typescript
// next.config.ts - Automatic llms.txt routing
async rewrites() {
  return [
    {
      source: '/docs/:path*.mdx',
      destination: '/api/content/docs/llms.mdx/:path*',
    },
    {
      source: '/blog/:path*.mdx',
      destination: '/api/content/blog/llms.mdx/:path*',
    },
    {
      source: '/help/:path*.mdx',
      destination: '/api/content/help/llms.mdx/:path*',
    },
    {
      source: '/updates/:path*.mdx',
      destination: '/api/content/updates/llms.mdx/:path*',
    },
  ]
}
```

This means any AI agent can access your content at URLs like:

* `yoursite.com/docs/getting-started/quickstart/llms.mdx`
* `yoursite.com/blog/announcements/llms.mdx`
* `yoursite.com/help/faq/llms.mdx`

### Content API Structure

The content is served through API routes in `src/app/(api)/api/content/` that automatically convert your MDX files into LLM-friendly formats. This includes:

* **Documentation**: All technical docs and guides
* **Blog posts**: Announcements, tutorials, and updates
* **Help center**: FAQs, troubleshooting, and support content
* **Release notes**: Version updates and changelogs

## Lia and llms.txt

While Lia comes pre-trained with deep knowledge of the Igniter.js ecosystem, she can optionally leverage `llms.txt` files for additional context:

### Built-in Training vs. Dynamic Context

* **Built-in Training**: Lia has specialized knowledge of Igniter.js patterns, multi-tenancy, and architecture
* **Dynamic Context**: She can use `llms.txt` to access the latest documentation, blog posts, and project updates
* **Hybrid Approach**: Best results come from combining Lia's training with fresh content via `llms.txt`

### Practical Usage

When working with Lia, you can reference `llms.txt` content for:

* Latest API changes or deprecations
* New feature announcements
* Updated best practices
* Recent troubleshooting guides

## Popular llms.txt Resources

Many popular libraries and frameworks provide `llms.txt` files for their documentation. Here's a curated list of useful resources:

| Library/Framework   | llms.txt URL                                                          | Description                      |
| ------------------- | --------------------------------------------------------------------- | -------------------------------- |
| **Next.js**         | [nextjs.org/docs/llms.txt](https://nextjs.org/docs/llms.txt)          | React framework documentation    |
| **Better Auth**     | [better-auth.com/docs/llms.txt](http://better-auth.com/docs/llms.txt) | Authentication library docs      |
| **Zod**             | [zod.dev/llms.txt](https://zod.dev/llms.txt)                          | TypeScript schema validation     |
| **Prisma**          | [prisma.io/docs/llms.txt](https://www.prisma.io/docs/llms.txt)        | Database ORM documentation       |
| **Fumadocs**        | [fumadocs.dev/llms.txt](https://fumadocs.dev/llms.txt)                | Documentation framework          |
| **Igniter.js Demo** | [demo.igniterjs.com/llms.txt](https://demo.igniterjs.com/llms.txt)    | Live demo of this implementation |

## Implementing llms.txt in Your Project

If you're extending Igniter.js or building your own implementation:

### Basic Setup

1. **Create the file**: Add `public/llms.txt` to your project
2. **Structure content**: Organize with clear sections and links
3. **Keep updated**: Regularly refresh with new content
4. **Test access**: Ensure the file is publicly accessible

## Best Practices

<Accordions type="multiple">
  <Accordion title="Keep it Focused">
    Don't include every single page—focus on high-value, frequently accessed content that AI agents would find most useful.
  </Accordion>

  <Accordion title="Maintain Structure">
    Use consistent formatting with clear headings and logical grouping of related topics.
  </Accordion>

  <Accordion title="Update Regularly">
    As your documentation evolves, keep the `llms.txt` file current to ensure AI agents have access to the latest information.
  </Accordion>

  <Accordion title="Test with AI Agents">
    Use tools like Lia to test that your `llms.txt` provides the context AI agents need for effective assistance.
  </Accordion>
</Accordions>


---

# Actions

> Master queries and mutations in Igniter.js to create type-safe API endpoints with automatic validation, full IntelliSense, and end-to-end type inference.
URL: https://igniterjs.com/docs/core/actions

## Overview

**Actions** are the core building blocks of your Igniter.js API. They define individual endpoints and come in two types:

* **Query** - For reading data (GET requests)
* **Mutation** - For modifying data (POST, PUT, DELETE, PATCH requests)

```typescript
import { igniter } from '@/igniter';

const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    // Query action
    list: igniter.query({
      name: 'List Users',
      description: 'Retrieve a list of all users',
      path: '/',
      handler: async ({ context, response }) => {
        const users = await context.db.users.findMany();
        return response.success({ users });
      }
    }),

    // Mutation action
    create: igniter.mutation({
      name: 'Create User',
      description: 'Create a new user account',
      path: '/',
      method: 'POST',
      body: CreateUserSchema,
      handler: async ({ request, response }) => {
        const user = await context.db.users.create(request.body);
        return response.created({ user });
      }
    })
  }
});
```

***

## Query Actions

Query actions are for **reading data**. They use the `GET` HTTP method and should be idempotent (multiple calls produce the same result).

### Basic Query

```typescript
const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    list: igniter.query({
      name: 'List Users',
      description: 'Retrieve a list of all users',
      path: '/',
      handler: async ({ context, response }) => {
        const users = await context.db.users.findMany();
        return response.success({ users });
      }
    })
  }
});

// Creates endpoint: GET /users/
```

### Query with Path Parameters

```typescript
const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    getById: igniter.query({
      name: 'Get User by ID',
      description: 'Retrieve a specific user by their ID',
      path: '/:id' as const, // add 'as const' to ensure type inference
      handler: async ({ request, context, response }) => {
        // ✅ request.params.id is automatically typed as string
        const user = await context.db.users.findUnique({
          where: { id: request.params.id }
        });

        if (!user) {
          return response.notFound({ message: 'User not found' });
        }

        return response.success({ user });
      }
    })
  }
});

// Creates endpoint: GET /users/:id
```

<Callout type="success" title="Automatic Type Inference">
  Path parameters are automatically extracted and typed from the path string! `/:id` → `params.id: string`
</Callout>

### Query with Query Parameters

Use Zod schemas to validate and type query parameters:

```typescript
import { z } from 'zod';

const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    search: igniter.query({
      name: 'Search Users',
      description: 'Search users by name with pagination',
      path: '/search',
      query: z.object({
        q: z.string().min(1),
        limit: z.coerce.number().optional().default(10),
        offset: z.coerce.number().optional().default(0)
      }),
      handler: async ({ request, context, response }) => {
        // ✅ request.query is fully typed and validated
        const { q, limit, offset } = request.query;

        const users = await context.db.users.findMany({
          where: {
            name: { contains: q, mode: 'insensitive' }
          },
          take: limit,
          skip: offset
        });

        return response.success({ users, query: q, limit, offset });
      }
    })
  }
});

// Creates endpoint: GET /users/search?q=john&limit=20&offset=0
```

<Callout type="info" title="z.coerce for Query Params">
  Query parameters come as strings from URLs. Use `z.coerce.number()` to automatically convert them to numbers!
</Callout>

### Query Options

<TypeTable
  type={{
path: {
  type: 'string',
  description: 'URL path (e.g., "/", "/:id", "/search")',
  required: true
},
query: {
  type: 'StandardSchemaV1',
  description: 'Query parameters validation schema (Zod, Valibot, Yup)',
  required: false
},
use: {
  type: 'IgniterProcedure[]',
  description: 'Middleware procedures to run before handler',
  required: false
},
handler: {
  type: 'IgniterActionHandler',
  description: 'The action handler function',
  required: true
},
name: {
  type: 'string',
  description: 'Optional name for documentation',
  required: false
},
description: {
  type: 'string',
  description: 'Optional description for documentation',
  required: false
}
}}
/>

<Callout type="success" title="OpenAPI Documentation">
  The `name` and `description` properties are crucial for generating comprehensive OpenAPI specifications for your API. They enable the CLI to create detailed documentation that powers **Igniter Studio** (our interactive API playground), making your API much more discoverable and user-friendly.
</Callout>

***

## Mutation Actions

Mutation actions are for **modifying data**. They support POST, PUT, PATCH, and DELETE methods.

### POST Mutation (Create)

```typescript
import { z } from 'zod';

const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    create: igniter.mutation({
      name: 'Create User',
      description: 'Create a new user account',
      path: '/',
      method: 'POST',
      body: z.object({
        name: z.string().min(2),
        email: z.string().email(),
        age: z.number().int().min(18).optional()
      }),
      handler: async ({ request, context, response }) => {
        // ✅ request.body is fully typed from CreateUserSchema
        const user = await context.db.users.create({
          data: request.body
        });

        return response.created({ user });
      }
    })
  }
});

// Creates endpoint: POST /users/
```

### PUT Mutation (Update)

```typescript
const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    update: igniter.mutation({
      name: 'Update User',
      description: 'Update an existing user by ID',
      path: '/:id' as const,
      method: 'PUT',
      body: z.object({
        name: z.string().min(2).optional(),
        email: z.string().email().optional(),
        age: z.number().int().min(18).optional()
      }),
      handler: async ({ request, context, response }) => {
        // ✅ request.params.id is typed
        // ✅ request.body is typed from UpdateUserSchema
        const user = await context.db.users.update({
          where: { id: request.params.id },
          data: request.body
        });

        return response.success({ user });
      }
    })
  }
});

// Creates endpoint: PUT /users/:id
```

### DELETE Mutation

```typescript
const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    delete: igniter.mutation({
      name: 'Delete User',
      description: 'Delete a user by ID',
      path: '/:id' as const,
      method: 'DELETE',
      handler: async ({ request, context, response }) => {
        await context.db.users.delete({
          where: { id: request.params.id }
        });

        return response.success({ message: 'User deleted successfully' });
      }
    })
  }
});

// Creates endpoint: DELETE /users/:id
```

### PATCH Mutation (Partial Update)

```typescript
const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    patch: igniter.mutation({
      name: 'Patch User',
      description: 'Partially update a user by ID',
      path: '/:id' as const,
      method: 'PATCH',
      body: z.object({
        name: z.string().min(2),
        email: z.string().email()
      }).partial(),
      handler: async ({ request, context, response }) => {
        const user = await context.db.users.update({
          where: { id: request.params.id },
          data: request.body
        });

        return response.success({ user });
      }
    })
  }
});

// Creates endpoint: PATCH /users/:id
```

### Mutation Options

<TypeTable
  type={{
path: {
  type: 'string',
  description: 'URL path (e.g., "/", "/:id")',
  required: true
},
method: {
  type: "'POST' | 'PUT' | 'DELETE' | 'PATCH'",
  description: 'HTTP method for the mutation',
  required: true
},
body: {
  type: 'StandardSchemaV1',
  description: 'Request body validation schema',
  required: false
},
query: {
  type: 'StandardSchemaV1',
  description: 'Query parameters validation schema',
  required: false
},
use: {
  type: 'IgniterProcedure[]',
  description: 'Middleware procedures to run before handler',
  required: false
},
handler: {
  type: 'IgniterActionHandler',
  description: 'The action handler function',
  required: true
},
name: {
  type: 'string',
  description: 'Optional name for documentation',
  required: false
},
description: {
  type: 'string',
  description: 'Optional description for documentation',
  required: false
}
}}
/>

***

## Action Handler

Every action has a `handler` function that processes the request and returns a response.

### Handler Context

The handler receives a context object with:

```typescript
handler: async ({ request, context, response, plugins }) => {
  // ...
}
```

<TypeTable
  type={{
request: {
  type: 'object',
  description: 'Request data (method, path, params, body, query, headers, cookies, raw)',
  required: true
},
context: {
  type: 'AppContext',
  description: 'Application context (db, user, services, etc.)',
  required: true
},
response: {
  type: 'IgniterResponseProcessor',
  description: 'Response helper methods (success, created, notFound, etc.)',
  required: true
},
plugins: {
  type: 'PluginRegistry',
  description: 'Type-safe access to plugin actions',
  required: true
}
}}
/>

### Request Object

```typescript
handler: async ({ request }) => {
  // HTTP method
  console.log(request.method);        // "GET" | "POST" | "PUT" | etc.
  
  // URL path
  console.log(request.path);          // "/users/123"
  
  // Path parameters (from /:param)
  console.log(request.params.id);     // "123" (typed!)
  
  // Query parameters (if schema defined)
  console.log(request.query.q);       // "search" (typed!)
  
  // Request body (if schema defined)
  console.log(request.body.name);     // "John" (typed!)
  
  // Headers
  const auth = request.headers.get('authorization');
  
  // Cookies
  const session = request.cookies.get('sessionId');
  
  // Raw Web Request object
  const rawRequest = request.raw;
}
```

### Context Object

```typescript
handler: async ({ context }) => {
  // Access app context (defined in Igniter.context())
  const users = await context.db.users.findMany();
  
  // Access user (if using dynamic context)
  if (context.user) {
    console.log('Authenticated:', context.user.email);
  }
  
  // Access services
  await context.email.send({ to: 'user@example.com' });
}
```

### Response Object

```typescript
handler: async ({ response }) => {
  // 200 OK with data
  return response.success({ users: [] });
  
  // 201 Created
  return response.created({ user: newUser });
  
  // 404 Not Found
  return response.notFound({ message: 'User not found' });
  
  // 400 Bad Request
  return response.badRequest({ message: 'Invalid input' });
  
  // 401 Unauthorized
  return response.unauthorized({ message: 'Authentication required' });
  
  // 500 Internal Server Error
  return response.error({ message: 'Something went wrong' });
  
  // Custom response
  return response.json({ custom: 'data' }, { status: 418 });
}
```

### Plugins Object

```typescript
handler: async ({ plugins, response }) => {
  // Call plugin actions (type-safe!)
  await plugins.audit.actions.create({
    action: 'user:created',
    userId: '123'
  });
  
  await plugins.email.actions.sendWelcome({
    to: 'user@example.com',
    name: 'John'
  });
  
  return response.success({ message: 'Done' });
}
```

***

## Validation

### Body Validation

```typescript
const postController = igniter.controller({
  name: 'Posts',
  description: 'Manage blog posts and articles',
  path: '/posts',
  actions: {
    create: igniter.mutation({
      name: 'Create Post',
      description: 'Create a new blog post',
      path: '/',
      method: 'POST',
      body: z.object({
        title: z.string().min(3).max(100),
        content: z.string().min(10),
        published: z.boolean().default(false),
        tags: z.array(z.string()).max(5).optional()
      }),
      handler: async ({ request, response }) => {
        // ✅ request.body is fully typed and validated
        const post = await db.posts.create({
          data: request.body
        });

        return response.created({ post });
      }
    })
  }
});
```

If validation fails, Igniter.js automatically returns a `400 Bad Request` with error details:

```json
{
  "error": "Validation failed",
  "issues": [
    {
      "path": ["title"],
      "message": "String must contain at least 3 character(s)"
    }
  ]
}
```

### Query Validation

```typescript
const productController = igniter.controller({
  path: '/products',
  actions: {
    search: igniter.query({
      path: '/search',
      query: z.object({
        q: z.string().min(1),
        category: z.enum(['tech', 'design', 'business']).optional(),
        minPrice: z.coerce.number().min(0).optional(),
        maxPrice: z.coerce.number().min(0).optional(),
        sortBy: z.enum(['price', 'date', 'popularity']).default('date')
      }),
      handler: async ({ request, response }) => {
        const { q, category, minPrice, maxPrice, sortBy } = request.query;
        
        const products = await db.products.findMany({
          where: {
            name: { contains: q },
            category: category,
            price: {
              gte: minPrice,
              lte: maxPrice
            }
          },
          orderBy: { [sortBy]: 'desc' }
        });
        
        return response.success({ products });
      }
    })
  }
});
```

### Combined Validation

You can validate both body and query parameters:

```typescript
const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    createWithInvite: igniter.mutation({
      name: 'Create User with Invite',
      description: 'Create a new user account using an invite code',
      path: '/',
      method: 'POST',
      body: z.object({
        name: z.string(),
        email: z.string().email()
      }),
      query: z.object({
        inviteCode: z.string().length(8)
      }),
      handler: async ({ request, response }) => {
        // ✅ Both request.body and request.query are typed
        const { name, email } = request.body;
        const { inviteCode } = request.query;

        // Verify invite
        const invite = await db.invites.findUnique({
          where: { code: inviteCode }
        });

        if (!invite) {
          return response.badRequest({ message: 'Invalid invite code' });
        }

        // Create user
        const user = await db.users.create({ data: { name, email } });

        return response.created({ user });
      }
    })
  }
});

// Usage: POST /users?inviteCode=ABC12345
// Body: { "name": "John", "email": "john@example.com" }
```

***

## Procedures (Middleware)

Add reusable logic before your handler using procedures:

```typescript
const authProcedure = igniter.procedure({
  handler: async ({ context, request }) => {
    const token = request.headers.get('authorization');
    
    if (!token) {
      throw new Error('No authorization token');
    }
    
    const user = await verifyToken(token);
    
    // ✅ Extend context with currentUser
    return {
      currentUser: user
    };
  }
});

const protectedController = igniter.controller({
  path: '/protected',
  actions: {
    getData: igniter.query({
      path: '/',
      use: [authProcedure],  // ← Apply middleware
      handler: async ({ context, response }) => {
        // ✅ context.currentUser is available!
        return response.success({
          message: `Hello, ${context.currentUser.name}`
        });
      }
    })
  }
});
```

***

## Error Handling

### Throwing Errors

```typescript
const userController = igniter.controller({
  path: '/users',
  actions: {
    getById: igniter.query({
      path: '/:id' as const,
      handler: async ({ request, context, response }) => {
        const user = await context.db.users.findUnique({
          where: { id: request.params.id }
        });
        
        if (!user) {
          // ✅ Option 1: Return error response
          return response.notFound({ message: 'User not found' });
        }
        
        // ✅ Option 2: Throw error (caught automatically)
        if (!user.isActive) {
          throw new Error('User account is deactivated');
        }
        
        return response.success({ user });
      }
    })
  }
});
```

### Custom Error Responses

```typescript
class UserNotFoundError extends Error {
  constructor(userId: string) {
    super(`User ${userId} not found`);
    this.name = 'UserNotFoundError';
  }
}

const handler = async ({ request, response }) => {
  try {
    const user = await findUser(request.params.id);
    return response.success({ user });
  } catch (error) {
    if (error instanceof UserNotFoundError) {
      return response.notFound({ message: error.message });
    }
    
    return response.error({ message: 'Unexpected error' });
  }
};
```

***

## Advanced Patterns

### Conditional Responses

```typescript
const userController = igniter.controller({
  path: '/users',
  actions: {
    list: igniter.query({
      path: '/',
      query: z.object({
        format: z.enum(['json', 'csv']).default('json')
      }),
      handler: async ({ request, context, response }) => {
        const users = await context.db.users.findMany();
        
        if (request.query.format === 'csv') {
          const csv = convertToCSV(users);
          return new Response(csv, {
            headers: { 'Content-Type': 'text/csv' }
          });
        }
        
        return response.success({ users });
      }
    })
  }
});
```

### Streaming Responses

```typescript
const fileController = igniter.controller({
  path: '/files',
  actions: {
    download: igniter.query({
      path: '/:id/download' as const,
      handler: async ({ request, context }) => {
        const file = await context.db.files.findUnique({
          where: { id: request.params.id }
        });
        
        const stream = await context.storage.getStream(file.path);
        
        return new Response(stream, {
          headers: {
            'Content-Type': file.mimeType,
            'Content-Disposition': `attachment; filename="${file.name}"`
          }
        });
      }
    })
  }
});
```

### Pagination

```typescript
const postController = igniter.controller({
  path: '/posts',
  actions: {
    list: igniter.query({
      path: '/',
      query: z.object({
        page: z.coerce.number().min(1).default(1),
        limit: z.coerce.number().min(1).max(100).default(20)
      }),
      handler: async ({ request, context, response }) => {
        const { page, limit } = request.query;
        const skip = (page - 1) * limit;
        
        const [posts, total] = await Promise.all([
          context.db.posts.findMany({ skip, take: limit }),
          context.db.posts.count()
        ]);
        
        return response.success({
          posts,
          pagination: {
            page,
            limit,
            total,
            totalPages: Math.ceil(total / limit),
            hasNext: page * limit < total,
            hasPrev: page > 1
          }
        });
      }
    })
  }
});
```

***

## Maintaining Actions

### Schema Generation After Changes

<Callout type="error">
  **Critical:** You MUST run schema generation BEFORE using the client in your frontend. The client depends on the generated schema to function correctly.
</Callout>

<Callout type="info">
  Run this command whenever you add, modify, or remove actions. This is required before using the client in your frontend.
</Callout>

When you add a new action or modify existing ones, regenerate the client schema:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="actions-maintenance">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest generate schema
    ```
  </Tab>
</Tabs>

This updates:

* `src/igniter.schema.ts` - Type definitions for your client
* `src/docs/openapi.json` - OpenAPI specification

***

## Next Steps

<Cards>
  <Card title="Controllers" href="/docs/controllers">
    Group actions into logical controllers
  </Card>

  <Card title="Procedures" href="/docs/procedures">
    Create reusable middleware logic
  </Card>

  <Card title="Validation" href="/docs/validation">
    Deep dive into schema validation
  </Card>

  <Card title="Response Types" href="/docs/response-types">
    Master all response helper methods
  </Card>
</Cards>


---

# Builder

> Learn how to configure and initialize your Igniter.js application using the powerful builder pattern with full type safety and IntelliSense.
URL: https://igniterjs.com/docs/core/builder

## Overview

The **Igniter Builder** is the foundation of your application. It provides a fluent, chainable API for configuring context, adapters, middleware, and creating fully typed API components.

```typescript
import { Igniter } from '@igniter-js/core';

const igniter = Igniter
  .context(createIgniterAppContext())
  .config({ baseURL: 'https://api.example.com' })
  .store(redisAdapter)
  .jobs(bullmqAdapter)
  .create();
```

<Callout type="info" title="Immutable Pattern">
  The builder uses an **immutable chaining pattern**. Each method returns a new instance with updated configuration, ensuring type safety throughout the entire chain.
</Callout>

***

## Core Concepts

### The Builder Pattern

Igniter.js uses the builder pattern to provide:

* ✅ **Progressive Type Enhancement** - Types become more specific as you configure
* ✅ **IntelliSense at Every Step** - Full autocomplete for all methods
* ✅ **Compile-Time Validation** - TypeScript catches configuration errors early
* ✅ **Flexible Configuration** - Add only what your application needs

### Configuration Flow

<Mermaid
  chart="
graph LR
A[Igniter] --> B[.context<T>]
B --> C[.config]
C --> D[.store]
D --> E[.jobs]
E --> F[.telemetry]
F --> G[.plugins]
G --> H[.create]
H --> I[Fully Typed API]
"
/>

***

## Builder Methods

### `.context<TContext>()`

Defines the **application-wide context type** that will be available in all actions, procedures, and middleware.

#### Static Context

Use a static object when your context doesn't depend on the request:

```typescript
interface AppContext {
  db: Database;
  config: AppConfig;
  services: {
    email: EmailService;
    storage: StorageService;
  };
}

// Create context factory function
export function createIgniterAppContext(): AppContext {
  return {
    db: new Database(),
    config: loadAppConfig(),
    services: {
      email: new EmailService(),
      storage: new StorageService()
    }
  };
}

const igniter = Igniter
  .context(createIgniterAppContext())
  .create();
```

#### Dynamic Context (Callback)

Use a callback function when context depends on the incoming request:

```typescript
type ContextCallback = (req: Request) => Promise<AppContext> | AppContext;

const igniter = Igniter
  .context(async (req: Request) => {
    const session = await getSession(req);
    const user = session ? await db.users.findById(session.userId) : null;
    
    return {
      db,
      user,
      session,
      requestId: crypto.randomUUID(),
      ip: req.headers.get('x-forwarded-for') || 'unknown'
    };
  })
  .create();
```

<Callout type="success" title="Type Inference">
  When using a callback, TypeScript automatically infers the context type from the return value. No manual type annotations needed!
</Callout>

#### Accessing Context in Actions

```typescript
const userController = igniter.controller({
  path: '/users',
  actions: {
    me: igniter.query({
      path: '/me',
      handler: async ({ context, response }) => {
        // ✅ context.user is fully typed
        if (!context.user) {
          return response.unauthorized({ message: 'Not authenticated' });
        }
        
        return response.success({ user: context.user });
      }
    })
  }
});
```

***

### `.config()`

Configures **router-level settings** like base URL and path prefix.

```typescript
const igniter = Igniter
  .context(createIgniterAppContext())
  .config({
    baseURL: 'https://api.example.com',
    basePATH: '/api/v1'
  })
  .create();
```

#### Configuration Options

<TypeTable
  type={{
baseURL: {
  type: 'string',
  description: 'The base URL for your API (used by client)',
  required: false
},
basePATH: {
  type: 'string',
  description: 'Path prefix for all routes (e.g., "/api/v1")',
  required: false
}
}}
/>

#### Usage Example

```typescript
// With this config:
.config({
  baseURL: 'https://api.example.com',
  basePATH: '/api/v1'
})

// A controller with path '/users'
igniter.controller({ path: '/users', ... })

// Creates routes at:
// https://api.example.com/api/v1/users
```

***

### `.store(adapter)`

Configures a **store adapter** for caching, key-value storage, and pub/sub messaging.

```typescript
import { createRedisStoreAdapter } from '@igniter-js/adapter-redis';

const redisStore = createRedisStoreAdapter({
  host: 'localhost',
  port: 6379,
  password: process.env.REDIS_PASSWORD
});

const igniter = Igniter
  .context(createIgniterAppContext())
  .store(redisStore)
  .create();
```

#### Using the Store

```typescript
const userController = igniter.controller({
  actions: {
    getCached: igniter.query({
      handler: async ({ context, response }) => {
        // ✅ Store is automatically available
        const cached = await igniter.store.get('users:list');
        
        if (cached) {
          return response.success({ users: JSON.parse(cached) });
        }
        
        const users = await context.db.users.findMany();
        await igniter.store.set('users:list', JSON.stringify(users), { ttl: 300 });
        
        return response.success({ users });
      }
    })
  }
});
```

<Callout type="info">
  Adding a store adapter also **automatically enables real-time capabilities** via the `.realtime` service.
</Callout>

***

### `.logger(adapter)`

Configures a **logger adapter** for structured logging.

```typescript
import { createConsoleLogger } from '@igniter-js/logger-console';

const logger = createConsoleLogger({
  level: 'info',
  colorize: true,
  context: { 
    service: 'api', 
    version: '1.0.0' 
  }
});

const igniter = Igniter
  .context(createIgniterAppContext())
  .logger(logger)
  .create();
```

#### Using the Logger

```typescript
const userController = igniter.controller({
  actions: {
    create: igniter.mutation({
      handler: async ({ request, response }) => {
        igniter.logger.info('Creating user', { 
          email: request.body.email 
        });
        
        try {
          const user = await db.users.create(request.body);
          igniter.logger.info('User created', { userId: user.id });
          return response.created({ user });
        } catch (error) {
          igniter.logger.error('Failed to create user', { error });
          return response.error({ message: 'Creation failed' });
        }
      }
    })
  }
});
```

***

### `.jobs(adapter)`

Configures a **job queue adapter** for background processing and scheduled tasks.

```typescript
import { createBullMQAdapter } from '@igniter-js/adapter-bullmq';

const jobsAdapter = createBullMQAdapter({
  store: redisStore,
  defaultJobOptions: {
    removeOnComplete: 10,
    removeOnFail: 50,
    attempts: 3,
    backoff: {
      type: 'exponential',
      delay: 1000
    }
  }
});

const igniter = Igniter
  .context(createIgniterAppContext())
  .store(redisStore)
  .jobs(jobsAdapter)
  .create();
```

#### Defining Jobs

```typescript
// Define your jobs with full type safety
const jobs = jobsAdapter.create({
  sendEmail: {
    handler: async (payload: { to: string; subject: string; body: string }) => {
      await emailService.send(payload);
    }
  },
  processOrder: {
    handler: async (payload: { orderId: string }) => {
      const order = await db.orders.findById(payload.orderId);
      await processOrderLogic(order);
    }
  }
});
```

#### Using Jobs in Actions

```typescript
const orderController = igniter.controller({
  actions: {
    create: igniter.mutation({
      handler: async ({ request, response }) => {
        const order = await db.orders.create(request.body);
        
        // ✅ Queue a background job
        await igniter.jobs.processOrder.add({ orderId: order.id });
        
        return response.created({ order });
      }
    })
  }
});
```

***

### `.telemetry(provider)`

Configures a **telemetry provider** for distributed tracing, metrics, and observability.

```typescript
import { createOpenTelemetryProvider } from '@igniter-js/adapter-opentelemetry';

const telemetry = createOpenTelemetryProvider({
  serviceName: 'igniter-api',
  serviceVersion: '1.0.0',
  tracing: {
    enabled: true,
    exporter: 'jaeger',
    endpoint: 'http://localhost:14268/api/traces'
  },
  metrics: {
    enabled: true,
    exporter: 'prometheus',
    port: 9464
  }
});

const igniter = Igniter
  .context(createIgniterAppContext())
  .telemetry(telemetry)
  .create();
```

#### Automatic Instrumentation

Telemetry automatically traces:

* ✅ HTTP requests and responses
* ✅ Action execution times
* ✅ Procedure (middleware) execution
* ✅ Database queries (if using supported ORMs)
* ✅ External API calls

#### Manual Spans

```typescript
const userController = igniter.controller({
  actions: {
    create: igniter.mutation({
      handler: async ({ request, response }) => {
        // Create custom span for specific operation
        const span = igniter.telemetry.startSpan('validate-user-data');
        
        try {
          await validateUserData(request.body);
          span.end();
        } catch (error) {
          span.recordException(error);
          span.end();
          throw error;
        }
        
        const user = await db.users.create(request.body);
        return response.created({ user });
      }
    })
  }
});
```

***

### `.plugins(pluginsRecord)`

Registers **plugins** to extend functionality with reusable, self-contained modules.

```typescript
import { createAuditPlugin } from './plugins/audit';
import { createAuthPlugin } from './plugins/auth';
import { createEmailPlugin } from './plugins/email';

const igniter = Igniter
  .context(createIgniterAppContext())
  .plugins({
    audit: createAuditPlugin(),
    auth: createAuthPlugin(),
    email: createEmailPlugin()
  })
  .create();
```

#### Using Plugins in Actions

```typescript
const userController = igniter.controller({
  actions: {
    create: igniter.mutation({
      handler: async ({ request, context, plugins, response }) => {
        // ✅ Full type safety for plugin actions
        const isValid = await plugins.auth.actions.validateToken({
          token: request.headers.get('authorization')
        });
        
        if (!isValid) {
          return response.unauthorized({ message: 'Invalid token' });
        }
        
        const user = await context.db.users.create(request.body);
        
        // ✅ Log to audit trail
        await plugins.audit.actions.create({
          action: 'user:created',
          userId: user.id,
          metadata: { email: user.email }
        });
        
        // ✅ Send welcome email
        await plugins.email.actions.sendWelcome({
          to: user.email,
          name: user.name
        });
        
        return response.created({ user });
      }
    })
  }
});
```

<Callout type="success" title="Plugin Type Safety">
  All plugin actions are fully typed! IntelliSense shows available actions, required parameters, and return types.
</Callout>

***

### `.docs(config)`

Configures **API documentation** and interactive playground using OpenAPI specification.

```typescript
const igniter = Igniter
  .context(createIgniterAppContext())
  .docs({
    openapi: '3.1.0',
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'A fully type-safe API built with Igniter.js'
    },
    servers: [
      { url: 'https://api.example.com', description: 'Production' },
      { url: 'http://localhost:3000', description: 'Development' }
    ],
    playground: {
      enabled: true,
      route: '/docs',
      security: async (req) => {
        // Protect playground in production
        return req.headers.get('x-admin-key') === process.env.ADMIN_KEY;
      }
    }
  })
  .create();
```

#### Documentation Options

<TypeTable
  type={{
openapi: {
  type: 'string',
  description: 'OpenAPI version (e.g., "3.1.0")',
  required: true
},
info: {
  type: 'OpenApiInfoObject',
  description: 'API metadata (title, version, description, contact, license)',
  required: false
},
servers: {
  type: 'OpenApiServerObject[]',
  description: 'Array of server configurations',
  required: false
},
securitySchemes: {
  type: 'Record<string, OpenApiSecuritySchemeObject>',
  description: 'Authentication schemes (API key, OAuth2, etc.)',
  required: false
},
playground: {
  type: 'object',
  description: 'Interactive API playground configuration',
  required: false
}
}}
/>

***

### `.create()`

Finalizes the builder and returns the **fully configured Igniter instance** with all methods available.

```typescript
const igniter = Igniter
  .context(createIgniterAppContext())
  .config({ baseURL: 'https://api.example.com' })
  .store(redisStore)
  .jobs(jobsAdapter)
  .create(); // ← Returns configured instance

// Now you can use:
igniter.query(...)
igniter.mutation(...)
igniter.controller(...)
igniter.router(...)
igniter.procedure(...)

// And access adapters:
igniter.store
igniter.logger
igniter.jobs
igniter.telemetry
igniter.realtime
igniter.plugins
```

<Callout type="warn" title="Must Call .create()">
  You **must call `.create()`** to finalize the builder. Without it, you won't have access to `query`, `mutation`, `controller`, and other methods.
</Callout>

***

## Complete Examples

### Minimal Setup

Perfect for getting started or simple APIs:

```typescript
import { Igniter } from '@igniter-js/core';

interface AppContext {
  db: Database;
}

const igniter = Igniter
  .context(createIgniterAppContext())
  .create();

// Ready to create actions!
```

### Production Setup

Full-featured configuration for production applications:

```typescript
import { Igniter } from '@igniter-js/core';
import { createRedisStoreAdapter } from '@igniter-js/adapter-redis';
import { createBullMQAdapter } from '@igniter-js/adapter-bullmq';
import { createOpenTelemetryProvider } from '@igniter-js/adapter-opentelemetry';

// 1. Setup adapters
const redisStore = createRedisStoreAdapter({
  host: process.env.REDIS_HOST,
  port: Number(process.env.REDIS_PORT),
  password: process.env.REDIS_PASSWORD
});

const jobsAdapter = createBullMQAdapter({
  store: redisStore,
  defaultJobOptions: {
    removeOnComplete: 10,
    removeOnFail: 50,
    attempts: 3
  }
});

const telemetry = createOpenTelemetryProvider({
  serviceName: 'my-api',
  serviceVersion: '1.0.0'
});

// 2. Create jobs
const jobs = jobsAdapter.create({
  sendEmail: { handler: async (payload) => { /* ... */ } },
  processOrder: { handler: async (payload) => { /* ... */ } }
});

// 3. Configure Igniter
const igniter = Igniter
  .context(async (req: Request) => {
    const session = await getSession(req);
    return {
      db: database,
      user: session?.user || null,
      requestId: crypto.randomUUID()
    };
  })
  .config({
    baseURL: process.env.API_URL,
    basePATH: '/api/v1'
  })
  .store(redisStore)
  .jobs(jobs)
  .telemetry(telemetry)
  .docs({
    openapi: '3.1.0',
    info: {
      title: 'My Production API',
      version: '1.0.0'
    },
    playground: {
      enabled: process.env.NODE_ENV === 'development',
      route: '/docs'
    }
  })
  .create();

export { igniter };
```

### With Plugins

Extending functionality with modular plugins:

```typescript
import { Igniter } from '@igniter-js/core';
import { auditPlugin } from './plugins/audit';
import { authPlugin } from './plugins/auth';
import { emailPlugin } from './plugins/email';

const igniter = Igniter
  .context(createIgniterAppContext())
  .store(redisStore)
  .plugins({
    audit: auditPlugin,
    auth: authPlugin,
    email: emailPlugin
  })
  .create();

// Use plugins in actions
const userController = igniter.controller({
  actions: {
    create: igniter.mutation({
      handler: async ({ plugins, response }) => {
        await plugins.audit.actions.log({ event: 'user:create' });
        await plugins.email.actions.send({ to: 'admin@example.com' });
        return response.success({ message: 'Done' });
      }
    })
  }
});
```

***

## Type Inference

The builder progressively enhances types as you configure:

```typescript
// Step 1: No context yet
const step1 = Igniter;
// Type: IgniterBuilder<{}, {}, ...>

// Step 2: Context added
const step2 = Igniter.context<{ db: Database }>();
// Type: IgniterBuilder<{ db: Database }, {}, ...>

// Step 3: Store added
const step3 = step2.store(redisStore);
// Type: IgniterBuilder<{ db: Database }, {}, RedisStoreAdapter, ...>

// Step 4: Created
const step4 = step3.create();
// Now has: .query(), .mutation(), .controller(), etc.
// Plus: .store, .logger, .jobs, .telemetry, .realtime, .plugins
```

<Callout type="success" title="Full IntelliSense">
  At every step, TypeScript provides complete autocomplete and type checking. You can't make invalid configurations!
</Callout>

***

## Adapter Access

After calling `.create()`, all configured adapters are available directly on the Igniter instance:

```typescript
const igniter = Igniter
  .context(createIgniterAppContext())
  .store(redisStore)
  .jobs(jobsAdapter)
  .telemetry(telemetry)
  .create();

// Access adapters anywhere:
igniter.store.get('key');
igniter.store.set('key', 'value');
igniter.store.subscribe('channel', callback);

igniter.jobs.sendEmail.add({ to: 'user@example.com' });
igniter.jobs.processOrder.addBulk([{ orderId: '1' }, { orderId: '2' }]);

igniter.telemetry.startSpan('operation-name');

igniter.realtime.broadcast('channel', { data: 'value' });
```

***

## Best Practices

### 1. Single Igniter Instance

Create **one Igniter instance** per application and export it:

```typescript
// src/igniter.ts
export const igniter = Igniter
  .context(createIgniterAppContext())
  .config({ baseURL: process.env.API_URL })
  .create();
```

```typescript
// src/features/users/users.controller.ts
import { igniter } from '@/igniter';

export const userController = igniter.controller({ /* ... */ });
```

### 2. Environment-Based Configuration

Use environment variables for different environments:

```typescript
const igniter = Igniter
  .context(createIgniterAppContext())
  .config({
    baseURL: process.env.NODE_ENV === 'production' 
      ? 'https://api.example.com' 
      : 'http://localhost:3000',
    basePATH: '/api/v1'
  })
  .docs({
    playground: {
      enabled: process.env.NODE_ENV === 'development'
    }
  })
  .create();
```

### 3. Reusable Context Functions

Extract context logic into reusable functions:

```typescript
async function createRequestContext(req: Request): Promise<AppContext> {
  const session = await getSession(req);
  const user = session ? await db.users.findById(session.userId) : null;
  
  return {
    db,
    user,
    requestId: crypto.randomUUID(),
    ip: req.headers.get('x-forwarded-for') || 'unknown'
  };
}

const igniter = Igniter
  .context(createRequestContext)
  .create();
```

### 4. Conditional Adapters

Only add adapters when needed:

```typescript
let builder = Igniter.context(createIgniterAppContext());

// Only add telemetry in production
if (process.env.NODE_ENV === 'production') {
  builder = builder.telemetry(telemetryProvider);
}

// Only add jobs if Redis is available
if (process.env.REDIS_URL) {
  builder = builder.store(redisStore).jobs(jobsAdapter);
}

const igniter = builder.create();
```

***

## Next Steps

Now that you understand the Builder, learn how to create APIs:

<Cards>
  <Card title="Router" href="/docs/router">
    Learn how to create routers and assemble your API
  </Card>

  <Card title="Actions" href="/docs/actions">
    Create queries and mutations for your endpoints
  </Card>

  <Card title="Controllers" href="/docs/controllers">
    Organize related actions into logical groups
  </Card>

  <Card title="Procedures" href="/docs/procedures">
    Add reusable middleware to your actions
  </Card>
</Cards>


---

# Context

> Master application context in Igniter.js with static and dynamic patterns for request-scoped data, dependency injection, and type-safe access.
URL: https://igniterjs.com/docs/core/context

## Overview

**Context** is the foundation of your Igniter.js application. It provides shared data and dependencies that are available to every action, procedure, and middleware throughout your API.

```typescript
import { Igniter } from '@igniter-js/core';

// Define context factory function in src/igniter.context.ts
export function createIgniterAppContext(): AppContext {
  return {
    db: new Database(),
    config: loadAppConfig(),
    services: {
      email: new EmailService(),
      storage: new StorageService()
    }
  };
}

const igniter = Igniter
  .context(createIgniterAppContext())
  .create();
```

<Callout type="info" title="What is Context?">
  Context is an object containing your application's dependencies (database, services, configuration) and request-specific data (user, session, request ID) that flows through every action.
</Callout>

***

## Context Types

Igniter.js supports two context patterns:

### Static Context

A **fixed object** that remains the same for all requests. Best for:

* ✅ Database connections
* ✅ Service instances
* ✅ Application configuration
* ✅ Shared utilities

```typescript
// src/igniter.context.ts
interface AppContext {
  db: Database;
  config: AppConfig;
  services: {
    email: EmailService;
    storage: StorageService;
  };
}

export function createIgniterAppContext(): AppContext {
  return {
    db: new Database(),
    config: loadAppConfig(),
    services: {
      email: new EmailService(),
      storage: new StorageService()
    }
  };
}

// src/igniter.ts
const igniter = Igniter
  .context(createIgniterAppContext())
  .create();
```

### Dynamic Context (Callback)

A **function** that creates context for each request. Best for:

* ✅ User authentication
* ✅ Session management
* ✅ Request IDs
* ✅ Per-request telemetry

```typescript
type ContextCallback = (req: Request) => Promise<AppContext> | AppContext;

const igniter = Igniter
  .context(async (req: Request) => {
    const session = await getSession(req);
    const user = session ? await db.users.findById(session.userId) : null;
    
    return {
      db,
      user,
      session,
      requestId: crypto.randomUUID(),
      ip: req.headers.get('x-forwarded-for') || 'unknown'
    };
  })
  .create();
```

***

## Static Context

### Defining Static Context

Use a type parameter to define your context shape:

```typescript
import { Igniter } from '@igniter-js/core';
import { db } from './lib/database';
import { emailService } from './lib/email';
import { storageService } from './lib/storage';

interface AppContext {
  db: Database;
  email: EmailService;
  storage: StorageService;
  config: {
    apiUrl: string;
    env: 'development' | 'production';
  };
}

const igniter = Igniter
  .context(createIgniterAppContext())
  .create();
```

<Callout type="warn" title="Type Only">
  With static context using `.context<T>()`, you're only defining the **type**. The actual context object is typically provided globally or through your framework's environment.
</Callout>

### Accessing Static Context

```typescript
const userController = igniter.controller({
  path: '/users',
  actions: {
    list: igniter.query({
      handler: async ({ context, response }) => {
        // ✅ context.db is fully typed as Database
        const users = await context.db.users.findMany();
        
        // ✅ context.email is EmailService
        await context.email.send({
          to: 'admin@example.com',
          subject: 'Users listed',
          body: `Found ${users.length} users`
        });
        
        return response.success({ users });
      }
    })
  }
});
```

### When to Use Static Context

Use static context when:

* Your dependencies don't change per request
* You don't need per-request isolation
* You want simpler configuration
* Performance is critical (no callback overhead)

**Example: Shared Services**

```typescript
import { PrismaClient } from '@prisma/client';
import { Redis } from 'ioredis';

const db = new PrismaClient();
const redis = new Redis();

interface AppContext {
  db: typeof db;
  redis: typeof redis;
  env: {
    nodeEnv: string;
    apiUrl: string;
  };
}

const igniter = Igniter
  .context(createIgniterAppContext())
  .create();
```

***

## Dynamic Context (Callback)

### Defining Dynamic Context

Pass a function that receives the `Request` object and returns context:

```typescript
import { Igniter } from '@igniter-js/core';

const igniter = Igniter
  .context(async (req: Request) => {
    // Extract auth token
    const token = req.headers.get('authorization')?.replace('Bearer ', '');
    
    // Get user from token
    const user = token ? await getUserFromToken(token) : null;
    
    // Get session
    const sessionId = req.headers.get('x-session-id');
    const session = sessionId ? await getSession(sessionId) : null;
    
    return {
      db,
      user,
      session,
      requestId: crypto.randomUUID(),
      timestamp: new Date(),
      ip: req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip') || 'unknown',
      userAgent: req.headers.get('user-agent') || 'unknown'
    };
  })
  .create();
```

### Accessing Dynamic Context

The context is **created fresh for each request** and injected into every action:

```typescript
const userController = igniter.controller({
  path: '/users',
  actions: {
    me: igniter.query({
      handler: async ({ context, response }) => {
        // ✅ context.user is inferred from callback return type
        if (!context.user) {
          return response.unauthorized({
            message: 'Authentication required'
          });
        }
        
        // ✅ Access request-specific data
        console.log('Request ID:', context.requestId);
        console.log('User IP:', context.ip);
        
        return response.success({
          user: context.user,
          session: context.session
        });
      }
    })
  }
});
```

### When to Use Dynamic Context

Use dynamic context when:

* You need authentication/authorization
* You want per-request isolation
* You need request-specific metadata (IDs, timestamps)
* You have request-dependent dependencies

**Example: Multi-Tenant Application**

```typescript
const igniter = Igniter
  .context(async (req: Request) => {
    // Extract tenant from subdomain or header
    const hostname = new URL(req.url).hostname;
    const tenant = hostname.split('.')[0];
    
    // Get tenant-specific database
    const db = await getTenantDatabase(tenant);
    
    // Get user
    const user = await getUserFromRequest(req);
    
    return {
      tenant,
      db,
      user,
      requestId: crypto.randomUUID()
    };
  })
  .create();
```

***

## Type Inference

### Automatic Inference from Callback

TypeScript automatically infers the context type from your callback's return value:

```typescript
const igniter = Igniter
  .context(async (req: Request) => {
    return {
      db: database,
      user: await getUser(req),
      timestamp: new Date()
    };
  })
  .create();

// ✅ Context type is automatically:
// {
//   db: typeof database;
//   user: User | null;
//   timestamp: Date;
// }
```

### Explicit Type Annotation

You can also explicitly type the callback:

```typescript
interface AppContext {
  db: Database;
  user: User | null;
  requestId: string;
}

const igniter = Igniter
  .context(async (req: Request): Promise<AppContext> => {
    return {
      db: database,
      user: await getUser(req),
      requestId: crypto.randomUUID()
    };
  })
  .create();
```

### Extracting Context Type

Get the context type from your router:

```typescript
const AppRouter = igniter.router({
  controllers: { users: userController }
});

// Extract context type
type AppContext = typeof AppRouter.$Infer.$context;

// Use in external functions
async function getUserData(context: AppContext) {
  return context.db.users.findMany();
}
```

***

## Context with Procedures

Procedures can **extend the context** by adding new properties:

```typescript
import { igniter } from '@/igniter';

// Create auth procedure that adds `currentUser`
const authProcedure = igniter.procedure({
  handler: async ({ context, request }) => {
    const token = request.headers.get('authorization');
    
    if (!token) {
      throw new Error('No authorization token');
    }
    
    const user = await verifyToken(token);
    
    // ✅ Extend context with currentUser
    return {
      currentUser: user
    };
  }
});

// Use in action
const protectedController = igniter.controller({
  path: '/protected',
  actions: {
    getData: igniter.query({
      path: '/',
      procedures: [authProcedure],
      handler: async ({ context, response }) => {
        // ✅ context.currentUser is available!
        console.log('Current user:', context.currentUser);
        
        return response.success({
          message: `Hello, ${context.currentUser.name}`
        });
      }
    })
  }
});
```

<Callout type="success" title="Type-Safe Extension">
  The context type automatically includes properties added by procedures. Full IntelliSense!
</Callout>

***

## Context Best Practices

### 1. Keep Context Lightweight

Don't load unnecessary data in context:

```typescript
// ❌ Bad - Loading everything upfront
const igniter = Igniter
  .context(async (req: Request) => {
    const user = await getUser(req);
    const posts = await db.posts.findMany({ userId: user.id });     // ❌ Not always needed
    const comments = await db.comments.findMany({ userId: user.id }); // ❌ Not always needed
    
    return { db, user, posts, comments };
  })
  .create();

// ✅ Good - Load only what's needed
const igniter = Igniter
  .context(async (req: Request) => {
    const user = await getUser(req);
    
    return { db, user };  // ✅ Load posts/comments in actions when needed
  })
  .create();
```

### 2. Use Lazy Loading

Create helper functions for optional data:

```typescript
const igniter = Igniter
  .context(async (req: Request) => {
    const userId = await getUserIdFromToken(req);
    
    return {
      db,
      userId,
      // ✅ Lazy loader for user data
      getUser: async () => {
        return userId ? await db.users.findById(userId) : null;
      },
      // ✅ Lazy loader for permissions
      getPermissions: async () => {
        return userId ? await db.permissions.findMany({ userId }) : [];
      }
    };
  })
  .create();

// Usage in action
const userController = igniter.controller({
  actions: {
    profile: igniter.query({
      handler: async ({ context, response }) => {
        // Only loads user if needed
        const user = await context.getUser();
        return response.success({ user });
      }
    })
  }
});
```

### 3. Cache Expensive Operations

Use memoization for expensive context operations:

```typescript
const igniter = Igniter
  .context(async (req: Request) => {
    const userId = await getUserIdFromToken(req);
    
    // ✅ Cache user data
    let cachedUser: User | null = null;
    
    return {
      db,
      userId,
      getUser: async () => {
        if (!cachedUser && userId) {
          cachedUser = await db.users.findById(userId);
        }
        return cachedUser;
      }
    };
  })
  .create();
```

### 4. Separate Concerns

Structure context into logical groups:

```typescript
const igniter = Igniter
  .context(async (req: Request) => {
    return {
      // Database
      db: database,
      
      // Authentication
      auth: {
        user: await getUser(req),
        session: await getSession(req),
        permissions: await getPermissions(req)
      },
      
      // Request metadata
      meta: {
        requestId: crypto.randomUUID(),
        timestamp: new Date(),
        ip: req.headers.get('x-forwarded-for') || 'unknown'
      },
      
      // Services
      services: {
        email: emailService,
        storage: storageService,
        analytics: analyticsService
      }
    };
  })
  .create();

// Usage
const handler = async ({ context, response }) => {
  console.log('User:', context.auth.user);
  console.log('Request ID:', context.meta.requestId);
  await context.services.email.send({ ... });
};
```

***

## Advanced Patterns

### Conditional Context

Adjust context based on request properties:

```typescript
const igniter = Igniter
  .context(async (req: Request) => {
    const isAdmin = req.headers.get('x-admin-key') === process.env.ADMIN_KEY;
    
    return {
      db,
      user: await getUser(req),
      isAdmin,
      // ✅ Admin-only database access
      adminDb: isAdmin ? adminDatabase : null
    };
  })
  .create();
```

### Multi-Tenant Context

Route requests to tenant-specific resources:

```typescript
const igniter = Igniter
  .context(async (req: Request) => {
    // Extract tenant from header or subdomain
    const tenant = req.headers.get('x-tenant-id') || extractTenantFromHost(req);
    
    if (!tenant) {
      throw new Error('Tenant not specified');
    }
    
    // Get tenant-specific database connection
    const db = await getTenantDatabase(tenant);
    
    return {
      tenant,
      db,
      user: await getUser(req),
      requestId: crypto.randomUUID()
    };
  })
  .create();
```

### Request Tracing Context

Add distributed tracing metadata:

```typescript
const igniter = Igniter
  .context(async (req: Request) => {
    const traceId = req.headers.get('x-trace-id') || crypto.randomUUID();
    const spanId = crypto.randomUUID();
    
    return {
      db,
      user: await getUser(req),
      trace: {
        traceId,
        spanId,
        parentSpanId: req.headers.get('x-parent-span-id') || null
      }
    };
  })
  .create();
```

***

## Context vs Procedures

| Feature          | Context                   | Procedures                |
| ---------------- | ------------------------- | ------------------------- |
| **When runs**    | Once per request          | For specific actions      |
| **Purpose**      | Provide base dependencies | Add action-specific logic |
| **Scope**        | All actions               | Selected actions          |
| **Type merging** | Base type                 | Extends base type         |
| **Performance**  | Runs for every request    | Runs only when needed     |

**Use context for:**

* Database connections
* Core services
* Request metadata
* User authentication (basic)

**Use procedures for:**

* Role-based authorization
* Input transformation
* Rate limiting
* Action-specific enrichment

***

## Complete Example

Here's a production-ready context setup:

```typescript
import { Igniter } from '@igniter-js/core';
import { PrismaClient } from '@prisma/client';
import { Redis } from 'ioredis';

// Services
const db = new PrismaClient();
const redis = new Redis(process.env.REDIS_URL);
const emailService = createEmailService();

// Context callback
const igniter = Igniter
  .context(async (req: Request) => {
    // Extract request metadata
    const requestId = crypto.randomUUID();
    const ip = req.headers.get('x-forwarded-for') || 'unknown';
    const userAgent = req.headers.get('user-agent') || 'unknown';
    
    // Authentication
    const token = req.headers.get('authorization')?.replace('Bearer ', '');
    let user = null;
    let session = null;
    
    if (token) {
      try {
        const decoded = await verifyJWT(token);
        user = await db.users.findUnique({ where: { id: decoded.userId } });
        session = await redis.get(`session:${decoded.sessionId}`);
      } catch (error) {
        console.error('Auth error:', error);
      }
    }
    
    return {
      // Core dependencies
      db,
      redis,
      
      // Services
      email: emailService,
      
      // Authentication
      user,
      session,
      
      // Request metadata
      requestId,
      ip,
      userAgent,
      timestamp: new Date(),
      
      // Feature flags
      features: {
        enableAnalytics: process.env.FEATURE_ANALYTICS === 'true',
        enableNotifications: process.env.FEATURE_NOTIFICATIONS === 'true'
      }
    };
  })
  .create();

export { igniter };
```

***

## Next Steps

<Cards>
  <Card title="Procedures" href="/docs/procedures">
    Learn how to extend context with reusable middleware
  </Card>

  <Card title="Actions" href="/docs/actions">
    Use context in queries and mutations
  </Card>

  <Card title="Error Handling" href="/docs/error-handling">
    Handle context errors gracefully
  </Card>

  <Card title="Testing" href="/docs/testing">
    Mock context for unit tests
  </Card>
</Cards>


---

# Controllers

> Learn how to organize actions into logical controllers with shared paths, group related endpoints, and build modular APIs with Igniter.js.
URL: https://igniterjs.com/docs/core/controllers

## Overview

**Controllers** group related actions together under a common path prefix. They help you organize your API into logical modules, making it easier to maintain and understand.

```typescript
import { igniter } from '@/igniter';

const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    list: igniter.query({ name: 'List Users', path: '/', handler: ... }),
    getById: igniter.query({ name: 'Get User', path: '/:id' as const, handler: ... }),
    create: igniter.mutation({ name: 'Create User', path: '/', method: 'POST', handler: ... }),
    update: igniter.mutation({ name: 'Update User', path: '/:id' as const, method: 'PUT', handler: ... }),
    delete: igniter.mutation({ name: 'Delete User', path: '/:id' as const, method: 'DELETE', handler: ... })
  }
});
```

<Callout type="info" title="What is a Controller?">
  A controller is a collection of **related actions** that share a common **path prefix**. All actions inside a controller automatically inherit the controller's path.
</Callout>

***

## Creating a Controller

### Basic Controller

```typescript
import { igniter } from '@/igniter';

const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    list: igniter.query({
      name: 'List Users',
      description: 'Retrieve all users',
      path: '/',
      handler: async ({ context, response }) => {
        const users = await context.db.users.findMany();
        return response.success({ users });
      }
    })
  }
});

// Creates endpoint: GET /users/
```

### Controller with Multiple Actions

```typescript
import { igniter } from '@/igniter';
import { z } from 'zod';

const CreateUserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email()
});

const UpdateUserSchema = CreateUserSchema.partial();

const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: {
    // GET /users/
    list: igniter.query({
      name: 'List Users',
      description: 'Retrieve all users',
      path: '/',
      handler: async ({ context, response }) => {
        const users = await context.db.users.findMany();
        return response.success({ users });
      }
    }),

    // GET /users/:id
    getById: igniter.query({
      name: 'Get User by ID',
      description: 'Retrieve a specific user by their ID',
      path: '/:id' as const,
      handler: async ({ request, context, response }) => {
        const user = await context.db.users.findUnique({
          where: { id: request.params.id }
        });
        
        if (!user) {
          return response.notFound({ message: 'User not found' });
        }
        
        return response.success({ user });
      }
    }),
    
    // POST /users/
    create: igniter.mutation({
      name: 'Create User',
      description: 'Create a new user account',
      path: '/',
      method: 'POST',
      body: CreateUserSchema,
      handler: async ({ request, context, response }) => {
        const user = await context.db.users.create({
          data: request.body
        });
        return response.created({ user });
      }
    }),

    // PUT /users/:id
    update: igniter.mutation({
      name: 'Update User',
      description: 'Update an existing user by ID',
      path: '/:id' as const,
      method: 'PUT',
      body: UpdateUserSchema,
      handler: async ({ request, context, response }) => {
        const user = await context.db.users.update({
          where: { id: request.params.id },
          data: request.body
        });
        return response.success({ user });
      }
    }),

    // DELETE /users/:id
    delete: igniter.mutation({
      name: 'Delete User',
      description: 'Delete a user by ID',
      path: '/:id' as const,
      method: 'DELETE',
      handler: async ({ request, context, response }) => {
        await context.db.users.delete({
          where: { id: request.params.id }
        });
        return response.success({ message: 'User deleted' });
      }
    })
  }
});
```

***

## Controller Configuration

### Path Prefix

The `path` property sets the base path for all actions in the controller:

```typescript
const postController = igniter.controller({
  name: 'Posts',
  description: 'Manage blog posts and articles',
  path: '/posts',  // ← Base path
  actions: {
    list: igniter.query({ name: 'List Posts', path: '/', ... }),        // → GET /posts/
    getById: igniter.query({ name: 'Get Post', path: '/:id' as const, ... }),  // → GET /posts/:id
    create: igniter.mutation({ name: 'Create Post', path: '/', ... })    // → POST /posts/
  }
});
```

<Callout type="success" title="Automatic Path Combination">
  Controller path (`/posts`) + Action path (`/:id`) = Full route (`/posts/:id`)
</Callout>

### Name and Description

Add metadata for documentation and OpenAPI generation:

```typescript
const userController = igniter.controller({
  name: 'Users',
  path: '/users',
  description: 'User management endpoints for authentication and profile data',
  actions: {
    // ...
  }
});
```

<Callout type="success" title="OpenAPI Documentation">
  The `name` and `description` properties are crucial for generating comprehensive OpenAPI specifications. They enable the CLI to create detailed documentation that powers **Igniter Studio** (our interactive API playground), making your API much more discoverable and user-friendly.
</Callout>

<TypeTable
  type={{
name: {
  type: 'string',
  description: 'Display name for documentation',
  required: false
},
path: {
  type: 'string',
  description: 'Base path prefix for all actions (e.g., "/users")',
  required: true
},
description: {
  type: 'string',
  description: 'Controller description for documentation',
  required: false
},
actions: {
  type: 'Record<string, IgniterAction>',
  description: 'Map of action name to action configuration',
  required: true
}
}}
/>

***

## Organizing Controllers

### Feature-Based Organization

Group controllers by feature or domain:

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="features" defaultOpen>
      <Folder name="users">
        <File name="user.controller.ts" />

        <File name="user.service.ts" />

        <File name="user.schema.ts" />
      </Folder>

      <Folder name="posts">
        <File name="post.controller.ts" />

        <File name="post.service.ts" />

        <File name="post.schema.ts" />
      </Folder>

      <Folder name="comments">
        <File name="comment.controller.ts" />

        <File name="comment.service.ts" />

        <File name="comment.schema.ts" />
      </Folder>
    </Folder>

    <File name="igniter.ts" />

    <File name="igniter.router.ts" />
  </Folder>
</Files>

```typescript
// features/users/user.controller.ts
export const userController = igniter.controller({
  name: 'Users',
  description: 'Manage user accounts and profiles',
  path: '/users',
  actions: { /* ... */ }
});

// features/posts/post.controller.ts
export const postController = igniter.controller({
  name: 'Posts',
  description: 'Manage blog posts and articles',
  path: '/posts',
  actions: { /* ... */ }
});

// igniter.router.ts
import { userController } from '@/features/users/user.controller';
import { postController } from '@/features/posts/post.controller';

export const AppRouter = igniter.router({
  controllers: {
    users: userController,
    posts: postController
  }
});
```

### Nested Paths

Create hierarchical APIs with nested paths:

```typescript
const postCommentController = igniter.controller({
  name: 'Post Comments',
  description: 'Manage comments on blog posts',
  path: '/posts/:postId/comments' as const,
  actions: {
    // GET /posts/:postId/comments/
    list: igniter.query({
      name: 'List Post Comments',
      description: 'Get all comments for a specific post',
      path: '/',
      handler: async ({ request, context, response }) => {
        const comments = await context.db.comments.findMany({
          where: { postId: request.params.postId }
        });
        return response.success({ comments });
      }
    }),

    // POST /posts/:postId/comments/
    create: igniter.mutation({
      name: 'Create Comment',
      description: 'Add a new comment to a post',
      path: '/',
      method: 'POST',
      body: CreateCommentSchema,
      handler: async ({ request, context, response }) => {
        const comment = await context.db.comments.create({
          data: {
            ...request.body,
            postId: request.params.postId
          }
        });
        return response.created({ comment });
      }
    }),
    
    // GET /posts/:postId/comments/:id
    getById: igniter.query({
      name: 'Get Comment',
      description: 'Retrieve a specific comment by ID',
      path: '/:id' as const,
      handler: async ({ request, context, response }) => {
        const comment = await context.db.comments.findUnique({
          where: { 
            id: request.params.id,
            postId: request.params.postId 
          }
        });
        
        if (!comment) {
          return response.notFound({ message: 'Comment not found' });
        }
        
        return response.success({ comment });
      }
    })
  }
});
```

***

## Common Patterns

### CRUD Controller

A complete CRUD (Create, Read, Update, Delete) controller:

```typescript
import { igniter } from '@/igniter';
import { z } from 'zod';

const CreateSchema = z.object({
  name: z.string(),
  description: z.string()
});

const UpdateSchema = CreateSchema.partial();

function createCrudController<T extends string>(resource: T) {
  const capitalizedResource = resource.charAt(0).toUpperCase() + resource.slice(1);

  return igniter.controller({
    name: `${capitalizedResource}`,
    description: `Manage ${resource} resources`,
    path: `/${resource}`,
    actions: {
      // List all
      list: igniter.query({
        name: `List ${capitalizedResource}`,
        description: `Retrieve all ${resource}`,
        path: '/',
        handler: async ({ context, response }) => {
          const items = await context.db[resource].findMany();
          return response.success({ [resource]: items });
        }
      }),

      // Get one by ID
      getById: igniter.query({
        name: `Get ${capitalizedResource}`,
        description: `Retrieve a specific ${resource} by ID`,
        path: '/:id' as const,
        handler: async ({ request, context, response }) => {
          const item = await context.db[resource].findUnique({
            where: { id: request.params.id }
          });
          
          if (!item) {
            return response.notFound({ message: `${resource} not found` });
          }
          
          return response.success({ [resource]: item });
        }
      }),
      
      // Create new
      create: igniter.mutation({
        name: `Create ${capitalizedResource}`,
        description: `Create a new ${resource}`,
        path: '/',
        method: 'POST',
        body: CreateSchema,
        handler: async ({ request, context, response }) => {
          const item = await context.db[resource].create({
            data: request.body
          });
          return response.created({ [resource]: item });
        }
      }),

      // Update existing
      update: igniter.mutation({
        name: `Update ${capitalizedResource}`,
        description: `Update an existing ${resource} by ID`,
        path: '/:id' as const,
        method: 'PUT',
        body: UpdateSchema,
        handler: async ({ request, context, response }) => {
          const item = await context.db[resource].update({
            where: { id: request.params.id },
            data: request.body
          });
          return response.success({ [resource]: item });
        }
      }),

      // Delete
      delete: igniter.mutation({
        name: `Delete ${capitalizedResource}`,
        description: `Delete a ${resource} by ID`,
        path: '/:id' as const,
        method: 'DELETE',
        handler: async ({ request, context, response }) => {
          await context.db[resource].delete({
            where: { id: request.params.id }
          });
          return response.success({ message: `${resource} deleted` });
        }
      })
    }
  });
}

// Usage
const productController = createCrudController('products');
const categoryController = createCrudController('categories');
```

### Search & Filter Controller

```typescript
const SearchSchema = z.object({
  q: z.string().min(1),
  category: z.string().optional(),
  minPrice: z.coerce.number().optional(),
  maxPrice: z.coerce.number().optional(),
  sortBy: z.enum(['price', 'date', 'name']).default('date'),
  order: z.enum(['asc', 'desc']).default('desc'),
  page: z.coerce.number().min(1).default(1),
  limit: z.coerce.number().min(1).max(100).default(20)
});

const productController = igniter.controller({
  name: 'Products',
  description: 'Manage product catalog with search and filtering',
  path: '/products',
  actions: {
    search: igniter.query({
      name: 'Search Products',
      description: 'Search and filter products with pagination',
      path: '/search',
      query: SearchSchema,
      handler: async ({ request, context, response }) => {
        const { q, category, minPrice, maxPrice, sortBy, order, page, limit } = request.query;
        const skip = (page - 1) * limit;
        
        const [products, total] = await Promise.all([
          context.db.products.findMany({
            where: {
              name: { contains: q, mode: 'insensitive' },
              category: category,
              price: {
                gte: minPrice,
                lte: maxPrice
              }
            },
            orderBy: { [sortBy]: order },
            skip,
            take: limit
          }),
          context.db.products.count({
            where: {
              name: { contains: q, mode: 'insensitive' },
              category: category
            }
          })
        ]);
        
        return response.success({
          products,
          pagination: {
            page,
            limit,
            total,
            totalPages: Math.ceil(total / limit)
          }
        });
      }
    })
  }
});
```

### Protected Controller

Apply authentication to all actions in a controller:

```typescript
const authProcedure = igniter.procedure({
  handler: async ({ context, request }) => {
    const token = request.headers.get('authorization')?.replace('Bearer ', '');
    
    if (!token) {
      throw new Error('Authentication required');
    }
    
    const user = await verifyToken(token);
    
    return {
      currentUser: user
    };
  }
});

const protectedController = igniter.controller({
  name: 'Protected',
  description: 'Protected endpoints requiring authentication',
  path: '/protected',
  actions: {
    getData: igniter.query({
      name: 'Get Protected Data',
      description: 'Retrieve user-specific protected data',
      path: '/data',
      use: [authProcedure],
      handler: async ({ context, response }) => {
        return response.success({
          message: `Hello, ${context.currentUser.name}`
        });
      }
    }),

    getSettings: igniter.query({
      name: 'Get User Settings',
      description: 'Retrieve user settings and preferences',
      path: '/settings',
      use: [authProcedure],
      handler: async ({ context, response }) => {
        const settings = await context.db.settings.findUnique({
          where: { userId: context.currentUser.id }
        });
        return response.success({ settings });
      }
    })
  }
});
```

***

## Versioned Controllers

Create multiple versions of the same controller:

```typescript
// v1/user.controller.ts
export const userControllerV1 = igniter.controller({
  name: 'Users API v1',
  description: 'Legacy user management API',
  path: '/v1/users',
  actions: {
    list: igniter.query({
      name: 'List Users v1',
      description: 'Retrieve users (legacy format)',
      path: '/',
      handler: async ({ context, response }) => {
        // Old implementation
        const users = await context.db.users.findMany({
          select: { id: true, name: true, email: true }
        });
        return response.success({ users });
      }
    })
  }
});

// v2/user.controller.ts
export const userControllerV2 = igniter.controller({
  name: 'Users API v2',
  description: 'Enhanced user management API',
  path: '/v2/users',
  actions: {
    list: igniter.query({
      name: 'List Users v2',
      description: 'Retrieve users with extended information',
      path: '/',
      handler: async ({ context, response }) => {
        // New implementation with additional fields
        const users = await context.db.users.findMany({
          select: {
            id: true,
            name: true,
            email: true,
            avatar: true,        // ← New field
            createdAt: true,     // ← New field
            role: true           // ← New field
          }
        });
        return response.success({ users });
      }
    })
  }
});

// Router
export const AppRouter = igniter.router({
  controllers: {
    usersV1: userControllerV1,  // /v1/users
    usersV2: userControllerV2   // /v2/users
  }
});
```

***

## Best Practices

### 1. Group by Domain

Organize controllers by business domain, not technical layers:

```typescript
// ✅ Good - Domain-based
const userController = igniter.controller({ path: '/users', ... });
const postController = igniter.controller({ path: '/posts', ... });
const commentController = igniter.controller({ path: '/comments', ... });

// ❌ Bad - Layer-based
const readController = igniter.controller({ path: '/read', ... });
const writeController = igniter.controller({ path: '/write', ... });
```

### 2. Keep Controllers Focused

Each controller should handle one resource or feature:

```typescript
// ✅ Good - Single responsibility
const userController = igniter.controller({
  path: '/users',
  actions: {
    list: ...,
    getById: ...,
    create: ...,
    update: ...,
    delete: ...
  }
});

// ❌ Bad - Mixed responsibilities
const apiController = igniter.controller({
  path: '/api',
  actions: {
    getUsers: ...,
    getPosts: ...,
    getComments: ...,
    createUser: ...,
    createPost: ...
  }
});
```

### 3. Use Consistent Naming

Follow RESTful conventions for action names:

```typescript
const resourceController = igniter.controller({
  name: 'Resources',
  description: 'Generic resource management',
  path: '/resources',
  actions: {
    list: igniter.query({
      name: 'List Resources',
      description: 'Retrieve all resources',
      path: '/', ...
    }),           // GET /resources
    getById: igniter.query({
      name: 'Get Resource',
      description: 'Retrieve a specific resource by ID',
      path: '/:id' as const, ...
    }),     // GET /resources/:id
    create: igniter.mutation({
      name: 'Create Resource',
      description: 'Create a new resource',
      method: 'POST', ...
    }), // POST /resources
    update: igniter.mutation({
      name: 'Update Resource',
      description: 'Update an existing resource',
      method: 'PUT', ...
    }),  // PUT /resources/:id
    delete: igniter.mutation({
      name: 'Delete Resource',
      description: 'Delete a resource by ID',
      method: 'DELETE', ...
    }) // DELETE /resources/:id
  }
});
```

### 4. Extract Shared Logic

Use procedures for shared validation or authorization:

```typescript
const adminOnlyProcedure = igniter.procedure({
  handler: async ({ context }) => {
    if (!context.user?.isAdmin) {
      throw new Error('Admin access required');
    }
    return {};
  }
});

const adminController = igniter.controller({
  path: '/admin',
  actions: {
    getUsers: igniter.query({
      use: [adminOnlyProcedure],
      handler: ...
    }),
    deleteUser: igniter.mutation({
      use: [adminOnlyProcedure],
      handler: ...
    })
  }
});
```

***

## Testing Controllers

### Unit Tests

Test individual actions:

```typescript
import { describe, it, expect } from 'vitest';
import { AppRouter } from '@/igniter.router';

describe('User Controller', () => {
  it('should list all users', async () => {
    const result = await AppRouter.caller.users.list.query();
    
    expect(result.data.users).toBeInstanceOf(Array);
  });

  it('should get user by ID', async () => {
    const result = await AppRouter.caller.users.getById.query({ id: '1' });
    
    expect(result.data.user).toBeDefined();
    expect(result.data.user.id).toBe('1');
  });

  it('should create a user', async () => {
    const result = await AppRouter.caller.users.create.mutate({
      body: {
        name: 'Test User',
        email: 'test@example.com'
      }
    });
    
    expect(result.data.user.name).toBe('Test User');
  });
});
```

### Integration Tests

Test full request flow:

```typescript
import { describe, it, expect } from 'vitest';

describe('User API Integration', () => {
  it('should handle user lifecycle', async () => {
    // Create
    const created = await AppRouter.caller.users.create.mutate({
      body: { name: 'John', email: 'john@example.com' }
    });
    const userId = created.data.user.id;
    
    // Read
    const read = await AppRouter.caller.users.getById.query({ id: userId });
    expect(read.data.user.name).toBe('John');
    
    // Update
    const updated = await AppRouter.caller.users.update.mutate({
      params: { id: userId },
      body: { name: 'Jane' }
    });
    expect(updated.data.user.name).toBe('Jane');
    
    // Delete
    await AppRouter.caller.users.delete.mutate({ params: { id: userId } });
    
    // Verify deletion
    await expect(
      AppRouter.caller.users.getById.query({ id: userId })
    ).rejects.toThrow();
  });
});
```

***

## Maintaining Controllers

### Schema Generation After Changes

<Callout type="error">
  **Critical:** You MUST run schema generation BEFORE using the client in your frontend. The client depends on the generated schema to function correctly.
</Callout>

<Callout type="info">
  Run this command whenever you add, modify, or remove controllers. This is required before using the client in your frontend.
</Callout>

When you add a new controller or modify existing ones, regenerate the client schema:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="controllers-maintenance">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest generate schema
    ```
  </Tab>
</Tabs>

This updates:

* `src/igniter.schema.ts` - Type definitions for your client
* `src/docs/openapi.json` - OpenAPI specification

***

## Next Steps

<Cards>
  <Card title="Actions" href="/docs/actions">
    Deep dive into queries and mutations
  </Card>

  <Card title="Procedures" href="/docs/procedures">
    Add middleware to your actions
  </Card>

  <Card title="Validation" href="/docs/validation">
    Master schema validation
  </Card>

  <Card title="Router" href="/docs/router">
    Assemble controllers into a router
  </Card>
</Cards>


---

# Procedures

> Create reusable middleware with Igniter.js procedures to handle authentication, validation, logging, and cross-cutting concerns with full type safety.
URL: https://igniterjs.com/docs/core/procedures

## Overview

**Procedures** are reusable middleware functions that run before your action handlers. They allow you to:

* ✅ Authenticate and authorize requests
* ✅ Validate and transform inputs
* ✅ Add request logging and tracing
* ✅ Inject dependencies into context
* ✅ Handle rate limiting
* ✅ Enrich context with computed data

```typescript
import { igniter } from '@/igniter';

const authProcedure = igniter.procedure({
  handler: async ({ context, request }) => {
    const token = request.headers.get('authorization');
    const user = await verifyToken(token);
    
    // ✅ Extend context with user
    return {
      currentUser: user
    };
  }
});

// Use in actions
const protectedAction = igniter.query({
  path: '/protected',
  use: [authProcedure],
  handler: async ({ context, response }) => {
    // ✅ context.currentUser is now available!
    return response.success({
      message: `Hello, ${context.currentUser.name}`
    });
  }
});
```

<Callout type="info" title="What is a Procedure?">
  A procedure is middleware that **runs before your action handler** and can **extend the context** with new properties. It's perfect for cross-cutting concerns.
</Callout>

***

## Creating Procedures

### Basic Procedure

```typescript
const timestampProcedure = igniter.procedure({
  handler: async ({ context }) => {
    return {
      requestTime: new Date(),
      timestamp: Date.now()
    };
  }
});

const userController = igniter.controller({
  path: '/users',
  actions: {
    list: igniter.query({
      use: [timestampProcedure],
      handler: async ({ context, response }) => {
        // ✅ context.requestTime and context.timestamp are available
        console.log('Request received at:', context.requestTime);
        
        const users = await context.db.users.findMany();
        return response.success({ users, timestamp: context.timestamp });
      }
    })
  }
});
```

### Authentication Procedure

```typescript
const authProcedure = igniter.procedure({
  handler: async ({ context, request, response }) => {
    const token = request.headers.get('authorization')?.replace('Bearer ', '');
    
    if (!token) {
      // ✅ Return early with error response
      return response.unauthorized({ message: 'No authorization token' });
    }
    
    try {
      const user = await verifyJWT(token);
      
      if (!user) {
        return response.unauthorized({ message: 'Invalid token' });
      }
      
      // ✅ Extend context with authenticated user
      return {
        currentUser: user,
        isAuthenticated: true
      };
    } catch (error) {
      return response.unauthorized({ message: 'Token verification failed' });
    }
  }
});
```

### Logging Procedure

```typescript
const requestLoggerProcedure = igniter.procedure({
  handler: async ({ request, context }) => {
    const requestId = crypto.randomUUID();
    const startTime = performance.now();
    
    context.logger?.info('Request started', {
      requestId,
      method: request.method,
      path: request.path,
      ip: request.headers.get('x-forwarded-for') || 'unknown',
      userAgent: request.headers.get('user-agent')
    });
    
    return {
      requestId,
      timing: {
        start: startTime,
        end: () => {
          const duration = performance.now() - startTime;
          context.logger?.info('Request completed', { requestId, duration });
          return duration;
        }
      }
    };
  }
});
```

***

## Procedure Handler

The procedure handler receives the same context as actions:

```typescript
handler: async ({ request, context, response, plugins }) => {
  // Access request data
  const token = request.headers.get('authorization');
  const userId = request.params.id;
  const query = request.query;
  
  // Access app context
  const user = await context.db.users.findUnique({ where: { id: userId } });
  
  // Return early with response
  if (!user) {
    return response.notFound({ message: 'User not found' });
  }
  
  // Or extend context
  return {
    currentUser: user,
    permissions: await getPermissions(user.id)
  };
}
```

<TypeTable
  type={{
request: {
  type: 'object',
  description: 'Request data (method, path, params, headers, cookies, etc.)',
  required: true
},
context: {
  type: 'AppContext',
  description: 'Application context from Igniter.context()',
  required: true
},
response: {
  type: 'IgniterResponseProcessor',
  description: 'Response helper methods (success, error, unauthorized, etc.)',
  required: true
},
plugins: {
  type: 'PluginRegistry',
  description: 'Type-safe access to plugin actions',
  required: true
}
}}
/>

***

## Context Extension

Procedures can **extend the context** by returning an object. The returned properties are merged into the context and available in subsequent procedures and the action handler.

### Single Extension

```typescript
const authProcedure = igniter.procedure({
  handler: async ({ request }) => {
    const user = await getUserFromToken(request);
    
    // ✅ Add user to context
    return {
      currentUser: user
    };
  }
});

// Usage
const action = igniter.query({
  use: [authProcedure],
  handler: async ({ context }) => {
    // ✅ context.currentUser is available and typed!
    console.log(context.currentUser.email);
  }
});
```

### Multiple Extensions

Procedures are executed in order, and each can extend the context:

```typescript
const authProcedure = igniter.procedure({
  handler: async ({ request }) => {
    return {
      currentUser: await getUserFromToken(request)
    };
  }
});

const permissionsProcedure = igniter.procedure({
  handler: async ({ context }) => {
    // ✅ Can access currentUser from previous procedure
    const permissions = await getPermissions(context.currentUser.id);
    
    return {
      permissions,
      can: (action: string) => permissions.includes(action)
    };
  }
});

// Usage
const action = igniter.query({
  use: [authProcedure, permissionsProcedure],
  handler: async ({ context }) => {
    // ✅ Both currentUser and permissions are available!
    if (!context.can('read:users')) {
      return response.forbidden({ message: 'Insufficient permissions' });
    }
  }
});
```

***

## Common Patterns

### Role-Based Authorization

```typescript
const requireRoleProcedure = igniter.procedure({
  handler: async ({ context, response }) => {
    if (!context.currentUser) {
      return response.unauthorized({ message: 'Authentication required' });
    }
    
    const userRoles = await context.db.userRoles.findMany({
      where: { userId: context.currentUser.id }
    });
    
    return {
      roles: userRoles.map(r => r.name),
      hasRole: (role: string) => userRoles.some(r => r.name === role),
      requireRole: (role: string) => {
        if (!userRoles.some(r => r.name === role)) {
          throw new Error(`Role '${role}' required`);
        }
      }
    };
  }
});

// Usage
const adminAction = igniter.query({
  use: [authProcedure, requireRoleProcedure],
  handler: async ({ context, response }) => {
    // ✅ Type-safe role check
    context.requireRole('admin');
    
    const users = await context.db.users.findMany();
    return response.success({ users });
  }
});
```

### Request Validation

```typescript
import { z } from 'zod';

const validateApiKeyProcedure = igniter.procedure({
  handler: async ({ request, response }) => {
    const apiKey = request.headers.get('x-api-key');
    
    if (!apiKey) {
      return response.unauthorized({ message: 'API key required' });
    }
    
    const keyRecord = await db.apiKeys.findUnique({
      where: { key: apiKey },
      include: { user: true }
    });
    
    if (!keyRecord || !keyRecord.isActive) {
      return response.unauthorized({ message: 'Invalid API key' });
    }
    
    return {
      apiKeyUser: keyRecord.user,
      apiKeyPermissions: keyRecord.permissions
    };
  }
});
```

### Rate Limiting

```typescript
const rateLimitProcedure = igniter.procedure({
  handler: async ({ request, context, response }) => {
    const ip = request.headers.get('x-forwarded-for') || 'unknown';
    const key = `rate_limit:${ip}`;
    
    // Increment request count
    const count = await context.store?.increment(key, { ttl: 60 }); // 60 seconds
    
    const limit = 100;
    const remaining = Math.max(0, limit - (count || 0));
    
    if ((count || 0) > limit) {
      return response.json(
        { message: 'Rate limit exceeded' },
        { 
          status: 429,
          headers: {
            'X-RateLimit-Limit': limit.toString(),
            'X-RateLimit-Remaining': '0',
            'X-RateLimit-Reset': (Date.now() + 60000).toString()
          }
        }
      );
    }
    
    return {
      rateLimit: {
        limit,
        remaining,
        current: count || 0
      }
    };
  }
});
```

### Request Tracing

```typescript
const tracingProcedure = igniter.procedure({
  handler: async ({ request, context }) => {
    const traceId = request.headers.get('x-trace-id') || crypto.randomUUID();
    const spanId = crypto.randomUUID();
    const parentSpanId = request.headers.get('x-parent-span-id') || null;
    
    const span = context.telemetry?.startSpan('http-request', {
      attributes: {
        'http.method': request.method,
        'http.path': request.path,
        'http.user_agent': request.headers.get('user-agent'),
        'trace.id': traceId,
        'span.id': spanId,
        'span.parent_id': parentSpanId
      }
    });
    
    return {
      trace: {
        traceId,
        spanId,
        parentSpanId,
        span,
        endSpan: () => span?.end()
      }
    };
  }
});
```

### Input Transformation

```typescript
const sanitizeInputProcedure = igniter.procedure({
  handler: async ({ request }) => {
    // Sanitize query parameters
    const sanitizedQuery = Object.entries(request.query || {}).reduce(
      (acc, [key, value]) => ({
        ...acc,
        [key]: typeof value === 'string' ? value.trim() : value
      }),
      {}
    );
    
    // Sanitize body
    const sanitizedBody = request.body ? 
      JSON.parse(JSON.stringify(request.body).replace(/<[^>]*>/g, '')) : 
      undefined;
    
    return {
      sanitized: {
        query: sanitizedQuery,
        body: sanitizedBody
      }
    };
  }
});
```

***

## Procedure Composition

### Chaining Procedures

Procedures run in order and can build on each other:

```typescript
const procedure1 = igniter.procedure({
  handler: async () => ({ step1: 'done' })
});

const procedure2 = igniter.procedure({
  handler: async ({ context }) => {
    // ✅ Access step1 from previous procedure
    console.log(context.step1);
    return { step2: 'done' };
  }
});

const procedure3 = igniter.procedure({
  handler: async ({ context }) => {
    // ✅ Access both step1 and step2
    console.log(context.step1, context.step2);
    return { step3: 'done' };
  }
});

// Use all three
const action = igniter.query({
  use: [procedure1, procedure2, procedure3],
  handler: async ({ context }) => {
    // ✅ All three steps are available
    console.log(context.step1, context.step2, context.step3);
  }
});
```

### Conditional Procedures

Create procedures that conditionally extend context:

```typescript
const optionalAuthProcedure = igniter.procedure({
  handler: async ({ request }) => {
    const token = request.headers.get('authorization');
    
    if (!token) {
      // ✅ Return minimal context if no token
      return {
        currentUser: null,
        isAuthenticated: false
      };
    }
    
    try {
      const user = await verifyToken(token);
      return {
        currentUser: user,
        isAuthenticated: true
      };
    } catch {
      return {
        currentUser: null,
        isAuthenticated: false
      };
    }
  }
});
```

***

## Error Handling

### Early Return with Response

Procedures can return a `Response` to short-circuit execution:

```typescript
const authProcedure = igniter.procedure({
  handler: async ({ request, response }) => {
    const token = request.headers.get('authorization');
    
    if (!token) {
      // ✅ Return response - action handler won't run
      return response.unauthorized({ message: 'Token required' });
    }
    
    const user = await verifyToken(token);
    return { currentUser: user };
  }
});
```

### Throwing Errors

You can also throw errors that will be caught automatically:

```typescript
const authProcedure = igniter.procedure({
  handler: async ({ request }) => {
    const token = request.headers.get('authorization');
    
    if (!token) {
      // ✅ Throw error - automatically returns 500
      throw new Error('No authorization token');
    }
    
    const user = await verifyToken(token);
    
    if (!user) {
      throw new Error('Invalid token');
    }
    
    return { currentUser: user };
  }
});
```

### Custom Error Classes

```typescript
class UnauthorizedError extends Error {
  statusCode = 401;
  constructor(message: string) {
    super(message);
    this.name = 'UnauthorizedError';
  }
}

const authProcedure = igniter.procedure({
  handler: async ({ request }) => {
    const token = request.headers.get('authorization');
    
    if (!token) {
      throw new UnauthorizedError('Token required');
    }
    
    const user = await verifyToken(token);
    return { currentUser: user };
  }
});
```

***

## Reusable Procedure Factories

Create factory functions for configurable procedures:

```typescript
function createAuthProcedure(options: { required: boolean }) {
  return igniter.procedure({
    handler: async ({ request, response }) => {
      const token = request.headers.get('authorization');
      
      if (!token) {
        if (options.required) {
          return response.unauthorized({ message: 'Token required' });
        }
        return { currentUser: null, isAuthenticated: false };
      }
      
      const user = await verifyToken(token);
      return { currentUser: user, isAuthenticated: true };
    }
  });
}

// Usage
const optionalAuth = createAuthProcedure({ required: false });
const requiredAuth = createAuthProcedure({ required: true });

const publicAction = igniter.query({
  use: [optionalAuth],
  handler: async ({ context }) => {
    // context.currentUser might be null
  }
});

const protectedAction = igniter.query({
  use: [requiredAuth],
  handler: async ({ context }) => {
    // context.currentUser is guaranteed
  }
});
```

***

## Best Practices

### 1. Keep Procedures Focused

Each procedure should have a single responsibility:

```typescript
// ✅ Good - Single responsibility
const authProcedure = igniter.procedure({
  handler: async ({ request }) => {
    const user = await authenticateUser(request);
    return { currentUser: user };
  }
});

const permissionsProcedure = igniter.procedure({
  handler: async ({ context }) => {
    const permissions = await getPermissions(context.currentUser.id);
    return { permissions };
  }
});

// ❌ Bad - Multiple responsibilities
const authAndPermissionsProcedure = igniter.procedure({
  handler: async ({ request, context }) => {
    const user = await authenticateUser(request);
    const permissions = await getPermissions(user.id);
    const settings = await getSettings(user.id);
    const preferences = await getPreferences(user.id);
    return { currentUser: user, permissions, settings, preferences };
  }
});
```

### 2. Use Type-Safe Returns

Always return typed objects:

```typescript
// ✅ Good - Typed return
interface AuthContext {
  currentUser: User;
  isAuthenticated: boolean;
}

const authProcedure = igniter.procedure({
  handler: async ({ request }): Promise<AuthContext> => {
    const user = await authenticateUser(request);
    return {
      currentUser: user,
      isAuthenticated: true
    };
  }
});
```

### 3. Order Matters

Place procedures in the correct order:

```typescript
// ✅ Correct order
const action = igniter.query({
  use: [
    requestLoggerProcedure,    // 1. Log request
    authProcedure,             // 2. Authenticate
    permissionsProcedure,      // 3. Check permissions (needs auth)
    rateLimitProcedure         // 4. Rate limit
  ],
  handler: async ({ context }) => { /* ... */ }
});

// ❌ Wrong order
const action = igniter.query({
  use: [
    permissionsProcedure,      // ❌ Runs before auth!
    authProcedure,
    requestLoggerProcedure
  ],
  handler: async ({ context }) => { /* ... */ }
});
```

### 4. Early Returns for Errors

Return error responses early to avoid unnecessary processing:

```typescript
const authProcedure = igniter.procedure({
  handler: async ({ request, response }) => {
    // ✅ Early return
    if (!request.headers.get('authorization')) {
      return response.unauthorized({ message: 'Token required' });
    }
    
    const user = await verifyToken(request.headers.get('authorization'));
    
    // ✅ Another early return
    if (!user.isActive) {
      return response.forbidden({ message: 'Account deactivated' });
    }
    
    return { currentUser: user };
  }
});
```

***

## Testing Procedures

### Unit Tests

Test procedures in isolation:

```typescript
import { describe, it, expect } from 'vitest';

describe('authProcedure', () => {
  it('should authenticate valid token', async () => {
    const mockRequest = {
      headers: new Headers({ 'authorization': 'Bearer valid-token' })
    };
    
    const result = await authProcedure.handler({
      request: mockRequest,
      context: {},
      response: mockResponseProcessor,
      plugins: {}
    });
    
    expect(result.currentUser).toBeDefined();
    expect(result.isAuthenticated).toBe(true);
  });

  it('should reject missing token', async () => {
    const mockRequest = {
      headers: new Headers()
    };
    
    const result = await authProcedure.handler({
      request: mockRequest,
      context: {},
      response: mockResponseProcessor,
      plugins: {}
    });
    
    expect(result.status).toBe(401);
  });
});
```

***

## Next Steps

<Cards>
  <Card title="Actions" href="/docs/actions">
    Use procedures in queries and mutations
  </Card>

  <Card title="Context" href="/docs/context">
    Understand how context flows through procedures
  </Card>

  <Card title="Error Handling" href="/docs/error-handling">
    Handle errors in procedures
  </Card>

  <Card title="Testing" href="/docs/testing">
    Test procedures and actions together
  </Card>
</Cards>


---

# Router

> Learn how to create and configure routers to assemble your API with full type safety, server-side calling, and HTTP handling.
URL: https://igniterjs.com/docs/core/router

## Overview

The **Router** is the central entrypoint for all HTTP requests in your Igniter.js application. It maps incoming requests to your controllers and actions, providing both HTTP handling and type-safe server-side invocation.

```typescript
import { igniter } from '@/igniter';
import { userController } from '@/features/users/user.controller';
import { postController } from '@/features/posts/post.controller';

export const AppRouter = igniter.router({
  controllers: {
    users: userController,
    posts: postController
  }
});
```

<Callout type="info" title="What is a Router?">
  A Router connects your **controllers** (grouped actions) to HTTP endpoints and provides a **type-safe caller** for server-side invocation without HTTP overhead.
</Callout>

***

## Creating a Router

### Basic Router

The simplest way to create a router is with the `igniter.router()` method:

```typescript
import { igniter } from '@/igniter';
import { userController } from './features/users/user.controller';

export const AppRouter = igniter.router({
  controllers: {
    users: userController
  }
});
```

This creates a router with:

* ✅ **HTTP handler** at `AppRouter.handler(request)`
* ✅ **Type-safe caller** at `AppRouter.caller.users.actionName()`
* ✅ **Full type inference** for all endpoints

### Multiple Controllers

Group related features into separate controllers:

```typescript
import { igniter } from '@/igniter';
import { userController } from './features/users/user.controller';
import { postController } from './features/posts/post.controller';
import { commentController } from './features/comments/comment.controller';

export const AppRouter = igniter.router({
  controllers: {
    users: userController,
    posts: postController,
    comments: commentController
  }
});
```

<Callout type="success">
  Each controller's `path` property is automatically prefixed to create full routes:

  * `/users/*` for `userController`
  * `/posts/*` for `postController`
  * `/comments/*` for `commentController`
</Callout>

***

## Router Properties

### `.handler(request)`

The **HTTP request handler** that processes incoming requests and routes them to the appropriate action.

```typescript
export const AppRouter = igniter.router({
  controllers: { users: userController }
});

// Use in Next.js API route
export async function POST(request: Request) {
  return AppRouter.handler(request);
}

// Use in Express
app.all('/api/*', async (req, res) => {
  const request = convertToWebRequest(req);
  const response = await AppRouter.handler(request);
  return sendWebResponse(res, response);
});

// Use in Bun
Bun.serve({
  port: 3000,
  fetch: AppRouter.handler
});
```

#### Request Processing Flow

```mermaid
graph LR
    A[HTTP Request] --> B[Router.handler]
    B --> C{Route Match?}
    C -->|Yes| D[Run Procedures]
    D --> E[Validate Input]
    E --> F[Execute Action]
    F --> G[Return Response]
    C -->|No| H[404 Not Found]
```

***

### `.caller`

The **type-safe server-side caller** allows you to invoke actions directly without HTTP overhead. Perfect for:

* ✅ Server-side rendering (SSR)
* ✅ Server components
* ✅ Integration tests
* ✅ Internal microservice calls

```typescript
export const AppRouter = igniter.router({
  controllers: {
    users: userController,
    posts: postController
  }
});

// Server-side usage
const user = await AppRouter.caller.users.getById.query({ id: '123' });
const post = await AppRouter.caller.posts.create.mutate({
  body: { title: 'Hello', content: 'World' }
});
```

<Callout type="info" title="No HTTP Overhead">
  The `.caller` bypasses the HTTP layer entirely, directly invoking your action handlers with full type safety. It's significantly faster than HTTP calls!
</Callout>

#### Caller API

The caller API matches your action types:

**For Query Actions:**

```typescript
// Query action (GET)
const result = await AppRouter.caller.users.list.query();
const user = await AppRouter.caller.users.getById.query({ id: '123' });
```

**For Mutation Actions:**

```typescript
// Mutation action (POST/PUT/DELETE/PATCH)
const created = await AppRouter.caller.users.create.mutate({
  body: { name: 'John', email: 'john@example.com' }
});

const updated = await AppRouter.caller.users.update.mutate({
  params: { id: '123' },
  body: { name: 'Jane' }
});

const deleted = await AppRouter.caller.users.delete.mutate({
  params: { id: '123' }
});
```

#### Full Input Object

The caller accepts the same input structure as client calls:

```typescript
const result = await AppRouter.caller.users.search.query({
  query: { q: 'john', limit: 10 },           // Query parameters
  headers: { 'x-api-key': 'secret' },        // Headers
  cookies: { sessionId: 'abc123' },          // Cookies
  credentials: 'include'                      // Credentials
});
```

***

### `.controllers`

Access to the registered controllers object:

```typescript
const AppRouter = igniter.router({
  controllers: {
    users: userController,
    posts: postController
  }
});

console.log(AppRouter.controllers.users);  // userController
console.log(AppRouter.controllers.posts);  // postController
```

***

### `.config`

The router configuration including `baseURL` and `basePATH`:

```typescript
const AppRouter = igniter.router({
  controllers: { users: userController }
});

console.log(AppRouter.config.baseURL);   // From Igniter config
console.log(AppRouter.config.basePATH);  // From Igniter config
```

***

## Framework Integration

### Next.js App Router

Create an API route that catches all requests:

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="app" defaultOpen>
      <Folder name="api" defaultOpen>
        <Folder name="v1" defaultOpen>
          <Folder name="[...path]" defaultOpen>
            <File name="route.ts" />
          </Folder>
        </Folder>
      </Folder>
    </Folder>

    <File name="igniter.router.ts" />
  </Folder>
</Files>

```typescript
// src/app/api/v1/[...path]/route.ts
import { AppRouter } from '@/igniter.router';

export async function GET(request: Request) {
  return AppRouter.handler(request);
}

export async function POST(request: Request) {
  return AppRouter.handler(request);
}

export async function PUT(request: Request) {
  return AppRouter.handler(request);
}

export async function DELETE(request: Request) {
  return AppRouter.handler(request);
}

export async function PATCH(request: Request) {
  return AppRouter.handler(request);
}
```

<Callout type="success">
  All HTTP methods route through `.handler()`, which automatically dispatches to the correct action based on path and method.
</Callout>

***

### Next.js Pages Router

```typescript
// pages/api/v1/[...path].ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { AppRouter } from '@/igniter.router';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  // Convert Next.js request to Web Request
  const request = new Request(
    `http://localhost:3000${req.url}`,
    {
      method: req.method,
      headers: req.headers as HeadersInit,
      body: req.method !== 'GET' ? JSON.stringify(req.body) : undefined
    }
  );

  const response = await AppRouter.handler(request);
  
  // Convert Web Response to Next.js response
  const data = await response.json();
  res.status(response.status).json(data);
}
```

***

### Express

```typescript
import express from 'express';
import { AppRouter } from './igniter.router';

const app = express();

app.use(express.json());

// Catch-all route
app.all('/api/v1/*', async (req, res) => {
  try {
    const request = new Request(
      `http://localhost:${port}${req.url}`,
      {
        method: req.method,
        headers: req.headers as HeadersInit,
        body: ['GET', 'HEAD'].includes(req.method) ? undefined : JSON.stringify(req.body)
      }
    );

    const response = await AppRouter.handler(request);
    const data = await response.json();
    
    res.status(response.status).json(data);
  } catch (error) {
    res.status(500).json({ error: 'Internal Server Error' });
  }
});

app.listen(3000);
```

***

### Bun

```typescript
// server.ts
import { AppRouter } from './igniter.router';

Bun.serve({
  port: 3000,
  fetch: AppRouter.handler,
});

console.log('Server running at http://localhost:3000');
```

<Callout type="success" title="Native Web APIs">
  Bun supports Web APIs natively, so you can use `AppRouter.handler` directly as the `fetch` handler!
</Callout>

***

### TanStack Start

```typescript
// app/routes/api.v1.$.ts
import { AppRouter } from '@/igniter.router';

export async function loader({ request }: { request: Request }) {
  return AppRouter.handler(request);
}

export async function action({ request }: { request: Request }) {
  return AppRouter.handler(request);
}
```

***

## Server-Side Usage

### React Server Components (Next.js)

```typescript
// app/users/page.tsx
import { AppRouter } from '@/igniter.router';

export default async function UsersPage() {
  // Direct server-side call - no HTTP!
  const { data } = await AppRouter.caller.users.list.query();

  return (
    <div>
      <h1>Users</h1>
      <ul>
        {data.users.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
}
```

### Server Actions (Next.js)

```typescript
'use server';

import { AppRouter } from '@/igniter.router';

export async function createUser(formData: FormData) {
  const name = formData.get('name') as string;
  const email = formData.get('email') as string;

  const result = await AppRouter.caller.users.create.mutate({
    body: { name, email }
  });

  return result;
}
```

### API Routes

```typescript
// app/api/internal/sync-users/route.ts
import { AppRouter } from '@/igniter.router';

export async function POST() {
  // Use caller for internal API routes
  const users = await AppRouter.caller.users.list.query();
  
  // Process users...
  
  return Response.json({ success: true });
}
```

***

## Testing with Caller

The `.caller` is perfect for integration tests:

```typescript
import { describe, it, expect } from 'vitest';
import { AppRouter } from '@/igniter.router';

describe('User API', () => {
  it('should create a user', async () => {
    const result = await AppRouter.caller.users.create.mutate({
      body: {
        name: 'Test User',
        email: 'test@example.com'
      }
    });

    expect(result.data.user).toMatchObject({
      name: 'Test User',
      email: 'test@example.com'
    });
  });

  it('should list all users', async () => {
    const result = await AppRouter.caller.users.list.query();
    
    expect(result.data.users).toBeInstanceOf(Array);
  });

  it('should get user by ID', async () => {
    // Create user first
    const created = await AppRouter.caller.users.create.mutate({
      body: { name: 'John', email: 'john@example.com' }
    });

    // Get by ID
    const result = await AppRouter.caller.users.getById.query({
      id: created.data.user.id
    });

    expect(result.data.user.name).toBe('John');
  });

  it('should handle not found', async () => {
    await expect(
      AppRouter.caller.users.getById.query({ id: 'non-existent' })
    ).rejects.toThrow();
  });
});
```

<Callout type="success" title="Fast Tests">
  Using `.caller` for tests is **much faster** than making HTTP requests. It directly invokes handlers with full type safety!
</Callout>

***

## Type Inference

The router provides complete type inference for both HTTP and caller usage:

```typescript
const AppRouter = igniter.router({
  controllers: {
    users: userController,
    posts: postController
  }
});

// ✅ Fully typed
type RouterType = typeof AppRouter;

// ✅ Extract caller type
type Caller = RouterType['caller'];

// ✅ Extract specific action
type UsersList = Caller['users']['list'];

// ✅ Use in functions
async function getUsers(): Promise<ReturnType<UsersList['query']>> {
  return AppRouter.caller.users.list.query();
}
```

### Infer Context Type

```typescript
type AppContext = typeof AppRouter.$Infer.$context;
// Result: The context type defined in Igniter.context<T>()
```

### Infer Plugins Type

```typescript
type AppPlugins = typeof AppRouter.$Infer.$plugins;
// Result: The plugins type defined in Igniter.plugins<T>()
```

***

## Advanced Patterns

### Multiple Routers

You can create multiple routers for different API versions or domains:

```typescript
// v1 router
export const AppRouterV1 = igniter.router({
  controllers: {
    users: userControllerV1,
    posts: postControllerV1
  }
});

// v2 router
export const AppRouterV2 = igniter.router({
  controllers: {
    users: userControllerV2,
    posts: postControllerV2,
    analytics: analyticsController  // New in v2
  }
});
```

```typescript
// app/api/v1/[...path]/route.ts
export async function GET(request: Request) {
  return AppRouterV1.handler(request);
}

// app/api/v2/[...path]/route.ts
export async function GET(request: Request) {
  return AppRouterV2.handler(request);
}
```

### Router Composition

Create domain-specific routers and compose them:

```typescript
// Public API router
export const PublicRouter = igniter.router({
  controllers: {
    auth: authController,
    products: productsController
  }
});

// Admin API router
export const AdminRouter = igniter.router({
  controllers: {
    users: adminUsersController,
    analytics: analyticsController,
    settings: settingsController
  }
});
```

***

## Best Practices

### 1. Single Export

Export your router from a central file:

```typescript
// src/igniter.router.ts
import { igniter } from '@/igniter';
import { userController } from '@/features/users/user.controller';
import { postController } from '@/features/posts/post.controller';

export const AppRouter = igniter.router({
  controllers: {
    users: userController,
    posts: postController
  }
});

export type AppRouterType = typeof AppRouter;
```

### 2. Use Caller for Server-Side

Always prefer `.caller` over HTTP requests when calling from the server:

```typescript
// ❌ Bad - HTTP overhead on same server
const response = await fetch('http://localhost:3000/api/v1/users');
const data = await response.json();

// ✅ Good - Direct invocation, faster and type-safe
const { data } = await AppRouter.caller.users.list.query();
```

### 3. Group Related Controllers

Organize controllers by feature or domain:

```typescript
export const AppRouter = igniter.router({
  controllers: {
    // User management
    users: userController,
    profiles: profileController,
    
    // Content
    posts: postController,
    comments: commentController,
    
    // Admin
    analytics: analyticsController,
    settings: settingsController
  }
});
```

### 4. Type-Safe Error Handling

```typescript
try {
  const result = await AppRouter.caller.users.getById.query({ id: '123' });
  console.log(result.data.user);
} catch (error) {
  // Errors are automatically thrown from .caller
  console.error('User not found:', error);
}
```

***

## Debugging

### Enable Request Logging

The router automatically logs requests when in development mode. You can also access logs programmatically:

```typescript
const response = await AppRouter.handler(request);

// Logs include:
// - Incoming request (URL, method, headers)
// - Parsed request (path, basePath, queryParams)
// - Routing decision (controller, action)
// - Response (status, headers, body)
```

### Inspect Router Structure

```typescript
console.log(AppRouter.controllers);  // All controllers
console.log(AppRouter.config);       // Router config
console.log(AppRouter.caller);       // Caller proxy
```

***

## Next Steps

Now that you understand routers, dive deeper into the building blocks:

<Cards>
  <Card title="Controllers" href="/docs/controllers">
    Learn how to group actions into controllers
  </Card>

  <Card title="Actions" href="/docs/actions">
    Create queries and mutations for your endpoints
  </Card>

  <Card title="Context" href="/docs/context">
    Understand static vs dynamic context patterns
  </Card>

  <Card title="Client" href="/docs/client">
    Use the type-safe client in your frontend
  </Card>
</Cards>


---

# Error Handling

> Master error handling in Igniter.js with IgniterError, IgniterResponseError, validation errors, custom error codes, and global error handlers.
URL: https://igniterjs.com/docs/core/error-handling

## Overview

**Error Handling** in Igniter.js is designed to be type-safe, structured, and developer-friendly. The framework provides built-in error classes, automatic validation error handling, and comprehensive error tracking through telemetry.

```typescript
import { IgniterError, IgniterResponseError } from '@igniter-js/core';

const getUser = igniter.query({
  path: '/users/:id' as const,
  handler: async ({ request, response, context }) => {
    const user = await context.db.users.findUnique({
      where: { id: request.params.id }
    });
    
    if (!user) {
      // ✅ Return typed error response
      return response.notFound('User not found');
    }
    
    // ✅ Or throw IgniterError for framework-level errors
    if (!user.isActive) {
      throw new IgniterError({
        message: 'User account is inactive',
        code: 'USER_INACTIVE',
        details: { userId: user.id },
        log: true
      });
    }
    
    return response.success({ user });
  }
});
```

<Callout type="success" title="Automatic Error Handling">
  Igniter.js automatically catches and formats all errors, including validation errors, framework errors, and uncaught exceptions.
</Callout>

***

## Error Response Structure

All errors follow a consistent structure:

```typescript
type IgniterResponse<TData, TError> = 
  | { data: TData; error: null }           // ✅ Success
  | { data: null; error: TError };         // ❌ Error
```

**Error Response Format:**

```json
{
  "data": null,
  "error": {
    "code": "ERR_NOT_FOUND",
    "message": "User not found",
    "data": {
      "userId": "123"
    }
  }
}
```

***

## Response Error Methods

### Built-in Error Responses

Igniter.js provides semantic error response methods:

```typescript
const action = igniter.query({
  handler: async ({ response }) => {
    // 400 Bad Request
    return response.badRequest('Invalid request data');
    
    // 401 Unauthorized
    return response.unauthorized('Authentication required');
    
    // 403 Forbidden
    return response.forbidden('Access denied');
    
    // 404 Not Found
    return response.notFound('Resource not found');
  }
});
```

**With Additional Data:**

```typescript
return response.badRequest('Validation failed', {
  fields: {
    email: 'Invalid format',
    age: 'Must be at least 18'
  }
});
```

***

## IgniterResponseError

The `IgniterResponseError` class represents client-facing errors:

### Creating Response Errors

```typescript
import { IgniterResponseError } from '@igniter-js/core';

const action = igniter.mutation({
  handler: async ({ response }) => {
    const error = new IgniterResponseError({
      code: 'ERR_BAD_REQUEST',
      message: 'Invalid input provided',
      data: {
        field: 'email',
        reason: 'already_exists'
      }
    });
    
    return response.error(error);
  }
});
```

### Common Error Codes

Igniter.js defines standard error codes:

| Code                | HTTP Status | Method                    |
| ------------------- | ----------- | ------------------------- |
| `ERR_BAD_REQUEST`   | 400         | `response.badRequest()`   |
| `ERR_UNAUTHORIZED`  | 401         | `response.unauthorized()` |
| `ERR_FORBIDDEN`     | 403         | `response.forbidden()`    |
| `ERR_NOT_FOUND`     | 404         | `response.notFound()`     |
| `ERR_REDIRECT`      | 302         | `response.redirect()`     |
| `ERR_UNKNOWN_ERROR` | 500         | Generic errors            |

### IgniterResponseError Methods

```typescript
const error = new IgniterResponseError({
  code: 'ERR_NOT_FOUND',
  message: 'User not found',
  data: { userId: '123' }
});

// Get error code
error.getCode(); // 'ERR_NOT_FOUND'

// Get message
error.getMessage(); // 'User not found'

// Get additional data
error.getData(); // { userId: '123' }

// Serialize to JSON
error.toJSON(); 
// { code: 'ERR_NOT_FOUND', message: 'User not found', data: { userId: '123' } }

// String representation
error.toString(); 
// 'IgniterResponseError [ERR_NOT_FOUND]: User not found'
```

***

## IgniterError (Framework Errors)

The `IgniterError` class is for **framework-level** errors (not client-facing):

### Creating Framework Errors

```typescript
import { IgniterError } from '@igniter-js/core';

throw new IgniterError({
  message: 'Database connection failed',
  code: 'DATABASE_ERROR',
  log: true,           // ✅ Logs to console with styled output
  details: {
    host: 'localhost',
    port: 5432
  },
  metadata: {
    timestamp: Date.now(),
    environment: process.env.NODE_ENV
  }
});
```

### IgniterError Properties

```typescript
class IgniterError extends Error {
  readonly code: string;         // Error code
  readonly details?: unknown;    // Additional error details
  readonly metadata?: Record<string, unknown>;  // Extra metadata
  readonly stackTrace?: string;  // Stack trace
}
```

### When to Use IgniterError

✅ **Use IgniterError for:**

* Database connection failures
* Configuration errors
* Initialization errors
* Plugin errors
* Internal framework issues

❌ **Don't use IgniterError for:**

* Validation errors (use schemas)
* Not found errors (use `response.notFound()`)
* Authorization errors (use `response.unauthorized()`)
* Client-facing errors (use `response.badRequest()`, etc.)

***

## Validation Errors

Validation errors are automatically handled:

### Schema Validation

```typescript
import { z } from 'zod';

const CreateUserSchema = z.object({
  email: z.string().email('Invalid email format'),
  age: z.number().min(18, 'Must be at least 18'),
  name: z.string().min(2, 'Name too short')
});

const action = igniter.mutation({
  method: 'POST',
  body: CreateUserSchema,
  handler: async ({ request, response }) => {
    // ✅ If validation fails, automatic 400 response
    const { email, age, name } = request.body;
  }
});
```

### Validation Error Response

Request:

```json
POST /users
{
  "email": "invalid-email",
  "age": 15,
  "name": "J"
}
```

Response (400 Bad Request):

```json
{
  "data": null,
  "error": {
    "message": "Validation Error",
    "code": "VALIDATION_ERROR",
    "details": [
      {
        "path": ["email"],
        "message": "Invalid email format"
      },
      {
        "path": ["age"],
        "message": "Must be at least 18"
      },
      {
        "path": ["name"],
        "message": "Name too short"
      }
    ]
  }
}
```

***

## Try-Catch in Actions

You can use try-catch for error handling:

### Basic Try-Catch

```typescript
const action = igniter.mutation({
  handler: async ({ response, context }) => {
    try {
      const result = await context.db.users.create({
        data: { email: 'user@example.com' }
      });
      return response.created({ user: result });
    } catch (error) {
      // Handle database errors
      if (error.code === 'P2002') {  // Prisma unique constraint
        return response.badRequest('Email already exists');
      }
      
      // Re-throw for global error handler
      throw error;
    }
  }
});
```

### Graceful Degradation

```typescript
const getRecommendations = igniter.query({
  handler: async ({ response, context }) => {
    try {
      // Try to get personalized recommendations
      const recommendations = await context.aiService.getRecommendations();
      return response.success({ recommendations });
    } catch (error) {
      // Fallback to popular items
      const popular = await context.db.products.findMany({
        orderBy: { views: 'desc' },
        take: 10
      });
      
      return response.success({
        recommendations: popular,
        fallback: true
      });
    }
  }
});
```

***

## Error Handler Processor

Igniter.js has a built-in `ErrorHandlerProcessor` that handles all errors:

### Error Types Handled

1. **Validation Errors** (Zod, Valibot, etc.)
   * Returns 400 with validation details
   * Logged as warnings
   * Tracked in telemetry

2. **IgniterError** (Framework errors)
   * Returns 500 with error details
   * Logged as errors with styled output
   * Tracked in telemetry

3. **Generic Errors** (Uncaught exceptions)
   * Returns 500 with generic error message
   * Logged as errors
   * Tracked in telemetry
   * Production mode hides stack traces

### How Error Handler Works

```typescript
// Internal Igniter.js flow:
try {
  // 1. Execute action handler
  const result = await handler(context);
  return result;
} catch (error) {
  // 2. ErrorHandlerProcessor catches error
  if (error.issues) {
    // Validation error → 400
    return ErrorHandlerProcessor.handleValidationError(error);
  }
  
  if (error instanceof IgniterError) {
    // Framework error → 500
    return ErrorHandlerProcessor.handleIgniterError(error);
  }
  
  // Generic error → 500
  return ErrorHandlerProcessor.handleGenericError(error);
}
```

***

## Custom Error Codes

### Define Custom Errors

```typescript
type CustomErrorCode = 
  | 'USER_SUSPENDED'
  | 'QUOTA_EXCEEDED'
  | 'PAYMENT_REQUIRED'
  | 'MAINTENANCE_MODE';

const action = igniter.query({
  handler: async ({ response }) => {
    const error = new IgniterResponseError<CustomErrorCode>({
      code: 'USER_SUSPENDED',
      message: 'Your account has been suspended',
      data: {
        reason: 'Terms of Service violation',
        suspendedAt: new Date(),
        contact: 'support@example.com'
      }
    });
    
    return response
      .status(403)
      .error(error);
  }
});
```

### Reusable Error Factory

```typescript
// utils/errors.ts
export const createUserError = (
  code: 'NOT_FOUND' | 'SUSPENDED' | 'DELETED',
  userId: string
) => {
  const messages = {
    NOT_FOUND: 'User not found',
    SUSPENDED: 'User account is suspended',
    DELETED: 'User account has been deleted'
  };
  
  return new IgniterResponseError({
    code: `USER_${code}`,
    message: messages[code],
    data: { userId }
  });
};

// Usage in actions
const getUser = igniter.query({
  path: '/users/:id' as const,
  handler: async ({ request, response, context }) => {
    const user = await context.db.users.findUnique({
      where: { id: request.params.id }
    });
    
    if (!user) {
      return response.error(createUserError('NOT_FOUND', request.params.id));
    }
    
    if (user.status === 'suspended') {
      return response.error(createUserError('SUSPENDED', user.id));
    }
    
    return response.success({ user });
  }
});
```

***

## Telemetry Integration

All errors are automatically tracked in telemetry:

```typescript
// Errors are logged with:
// - Error code
// - Error message
// - Stack trace
// - Request context (path, method, headers)
// - Timing information
// - Custom metadata

const action = igniter.query({
  handler: async ({ response }) => {
    throw new IgniterError({
      message: 'External API failed',
      code: 'EXTERNAL_API_ERROR',
      metadata: {
        service: 'stripe',
        endpoint: '/v1/charges',
        statusCode: 503
      }
    });
    // ✅ Automatically tracked in OpenTelemetry
  }
});
```

***

## Best Practices

### 1. Use Semantic Error Methods

```typescript
// ✅ Good - Clear intent
return response.notFound('User not found');

// ❌ Bad - Less semantic
return response.status(404).json({ error: 'Not found' });
```

### 2. Provide Meaningful Error Messages

```typescript
// ✅ Good - Helpful to developers and users
return response.badRequest('Email is required and must be valid', {
  field: 'email',
  constraint: 'email_format'
});

// ❌ Bad - Generic
return response.badRequest('Bad request');
```

### 3. Use Validation Schemas, Not Manual Checks

```typescript
// ✅ Good - Automatic validation
const action = igniter.mutation({
  body: z.object({ email: z.string().email() }),
  handler: async ({ request }) => {
    // request.body.email is validated
  }
});

// ❌ Bad - Manual validation
const action = igniter.mutation({
  handler: async ({ request, response }) => {
    if (!request.body.email) {
      return response.badRequest('Email required');
    }
    if (!isValidEmail(request.body.email)) {
      return response.badRequest('Invalid email');
    }
  }
});
```

### 4. Don't Expose Sensitive Errors in Production

```typescript
const action = igniter.query({
  handler: async ({ response, context }) => {
    try {
      return await context.db.users.findMany();
    } catch (error) {
      if (process.env.NODE_ENV === 'production') {
        // ✅ Generic error in production
        return response.error(new IgniterResponseError({
          code: 'ERR_UNKNOWN_ERROR',
          message: 'An error occurred'
        }));
      } else {
        // ✅ Detailed error in development
        return response.error(new IgniterResponseError({
          code: 'DATABASE_ERROR',
          message: error.message,
          data: { stack: error.stack }
        }));
      }
    }
  }
});
```

### 5. Log Framework Errors

```typescript
// ✅ Good - Logs styled error
throw new IgniterError({
  message: 'Redis connection failed',
  code: 'REDIS_ERROR',
  log: true,  // ✅ Logs to console
  details: { host: 'localhost', port: 6379 }
});

// ❌ Bad - Silent failure
throw new Error('Redis failed');
```

***

## Common Error Patterns

### Resource Not Found

```typescript
const getResource = igniter.query({
  path: '/:id' as const,
  handler: async ({ request, response, context }) => {
    const resource = await context.db.resources.findUnique({
      where: { id: request.params.id }
    });
    
    if (!resource) {
      return response.notFound(`Resource ${request.params.id} not found`);
    }
    
    return response.success({ resource });
  }
});
```

### Authorization Errors

```typescript
const deletePost = igniter.mutation({
  path: '/posts/:id' as const,
  method: 'DELETE',
  handler: async ({ request, context, response }) => {
    const post = await context.db.posts.findUnique({
      where: { id: request.params.id }
    });
    
    if (!post) return response.notFound();
    
    // Check ownership
    if (post.authorId !== context.user.id) {
      return response.forbidden('You can only delete your own posts');
    }
    
    await context.db.posts.delete({ where: { id: post.id } });
    return response.noContent();
  }
});
```

### External API Failures

```typescript
const getExternalData = igniter.query({
  handler: async ({ response }) => {
    try {
      const data = await fetch('https://api.example.com/data');
      return response.success({ data });
    } catch (error) {
      throw new IgniterError({
        message: 'External API request failed',
        code: 'EXTERNAL_API_ERROR',
        log: true,
        details: {
          url: 'https://api.example.com/data',
          error: error.message
        }
      });
    }
  }
});
```

***

## Next Steps

<Cards>
  <Card title="Response Types" href="/docs/response-types">
    Learn all response methods
  </Card>

  <Card title="Validation" href="/docs/validation">
    Validate input with schemas
  </Card>

  <Card title="Procedures" href="/docs/procedures">
    Handle errors in procedures
  </Card>

  <Card title="Testing" href="/docs/testing">
    Test error handling
  </Card>
</Cards>


---

# Response Types

> Master all response types in Igniter.js including success, error, streaming, cookies, headers, and cache revalidation for building robust APIs.
URL: https://igniterjs.com/docs/core/response-types

## Overview

**Response Types** in Igniter.js provide a comprehensive, type-safe API for constructing HTTP responses. The `response` object available in action handlers gives you full control over status codes, headers, cookies, body content, streaming, and client-side cache revalidation.

```typescript
const userController = igniter.controller({
  path: '/users',
  actions: {
    getUser: igniter.query({
      path: '/:id' as const,
      handler: async ({ request, response, context }) => {
        const user = await context.db.users.findUnique({
          where: { id: request.params.id }
        });
        
        if (!user) {
          return response.notFound('User not found');
        }
        
        return response.success({ user });
      }
    })
  }
});
```

<Callout type="success" title="Fluent Interface">
  All response methods are **chainable**, allowing you to build complex responses in a fluent, type-safe manner.
</Callout>

***

## Success Responses

### response.success()

Returns a `200 OK` response with data:

```typescript
const action = igniter.query({
  path: '/users',
  handler: async ({ response, context }) => {
    const users = await context.db.users.findMany();
    
    // ✅ Returns 200 OK with typed data
    return response.success({ users });
  }
});
```

**TypeScript Inference:**

```typescript
const result = response.success({ users: [] });
// result is typed as: IgniterResponse<{ users: User[] }>
```

### response.created()

Returns a `201 Created` response, typically after creating a resource:

```typescript
const createUser = igniter.mutation({
  path: '/users',
  method: 'POST',
  body: CreateUserSchema,
  handler: async ({ request, response, context }) => {
    const user = await context.db.users.create({
      data: request.body
    });
    
    // ✅ Returns 201 Created
    return response.created({ user });
  }
});
```

### response.noContent()

Returns a `204 No Content` response (commonly used for DELETE operations):

```typescript
const deleteUser = igniter.mutation({
  path: '/users/:id' as const,
  method: 'DELETE',
  handler: async ({ request, response, context }) => {
    await context.db.users.delete({
      where: { id: request.params.id }
    });
    
    // ✅ Returns 204 No Content (no body)
    return response.noContent();
  }
});
```

<Callout type="info" title="RFC 7231 Compliance">
  `response.noContent()` returns HTTP 204 with **no body** and **no Content-Type header**, compliant with RFC 7231.
</Callout>

### response.json()

Generic JSON response (you can control status manually):

```typescript
const action = igniter.query({
  handler: async ({ response }) => {
    return response
      .status(200)
      .json({ message: 'Custom JSON response' });
  }
});
```

***

## Error Responses

### response.badRequest()

Returns `400 Bad Request`:

```typescript
const action = igniter.mutation({
  handler: async ({ request, response }) => {
    if (!request.body.email) {
      return response.badRequest('Email is required');
    }
    
    // Continue...
  }
});
```

**With Additional Data:**

```typescript
return response.badRequest('Validation failed', {
  fields: {
    email: 'Invalid format',
    password: 'Too short'
  }
});
```

### response.unauthorized()

Returns `401 Unauthorized`:

```typescript
const protectedAction = igniter.query({
  handler: async ({ context, response }) => {
    if (!context.user) {
      return response.unauthorized('Authentication required');
    }
    
    // User is authenticated
  }
});
```

### response.forbidden()

Returns `403 Forbidden` (authenticated but not allowed):

```typescript
const deletePost = igniter.mutation({
  path: '/posts/:id' as const,
  method: 'DELETE',
  handler: async ({ request, context, response }) => {
    const post = await context.db.posts.findUnique({
      where: { id: request.params.id }
    });
    
    if (post.authorId !== context.user.id) {
      return response.forbidden('You can only delete your own posts');
    }
    
    // User is authorized
    await context.db.posts.delete({ where: { id: post.id } });
    return response.noContent();
  }
});
```

### response.notFound()

Returns `404 Not Found`:

```typescript
const getUser = igniter.query({
  path: '/users/:id' as const,
  handler: async ({ request, response, context }) => {
    const user = await context.db.users.findUnique({
      where: { id: request.params.id }
    });
    
    if (!user) {
      return response.notFound('User not found');
    }
    
    return response.success({ user });
  }
});
```

### response.error()

Generic error handler with custom error code:

```typescript
import { IgniterResponseError } from '@igniter-js/core';

const action = igniter.mutation({
  handler: async ({ response }) => {
    const error = new IgniterResponseError({
      code: 'ERR_CUSTOM',
      message: 'Something went wrong',
      data: { details: 'Additional error context' }
    });
    
    return response
      .status(500)
      .error(error);
  }
});
```

***

## Redirects

### response.redirect()

Creates a redirect response:

```typescript
const legacyRoute = igniter.query({
  path: '/old-route',
  handler: async ({ response }) => {
    // ✅ Returns 302 redirect (default)
    return response.redirect('/new-route', 'replace');
  }
});
```

**Redirect Types:**

* `'replace'`: Replaces current URL (default, HTTP 302)
* `'push'`: Adds to browser history (HTTP 302)

**Custom Status:**

```typescript
return response
  .status(301) // Permanent redirect
  .redirect('/new-route', 'replace');
```

***

## Headers and Cookies

### response.setHeader()

Set custom headers:

```typescript
const action = igniter.query({
  handler: async ({ response }) => {
    return response
      .setHeader('Cache-Control', 'public, max-age=3600')
      .setHeader('X-Custom-Header', 'value')
      .success({ data: [] });
  }
});
```

### response.setCookie()

Set cookies with full control:

```typescript
const login = igniter.mutation({
  path: '/auth/login',
  method: 'POST',
  handler: async ({ response }) => {
    const token = 'jwt-token-here';
    
    return response
      .setCookie('session', token, {
        httpOnly: true,      // ✅ Not accessible via JavaScript
        secure: true,        // ✅ HTTPS only
        sameSite: 'strict',  // ✅ CSRF protection
        maxAge: 3600,        // ✅ 1 hour
        path: '/',
        domain: 'example.com'
      })
      .success({ message: 'Logged in' });
  }
});
```

**Cookie Options:**

| Option        | Type                          | Description                              |
| ------------- | ----------------------------- | ---------------------------------------- |
| `httpOnly`    | `boolean`                     | Prevents JavaScript access (security)    |
| `secure`      | `boolean`                     | HTTPS only                               |
| `sameSite`    | `'strict' \| 'lax' \| 'none'` | CSRF protection                          |
| `maxAge`      | `number`                      | Max age in seconds                       |
| `expires`     | `Date`                        | Absolute expiration date                 |
| `path`        | `string`                      | Cookie path                              |
| `domain`      | `string`                      | Cookie domain                            |
| `partitioned` | `boolean`                     | CHIPS (partitioned cookies)              |
| `prefix`      | `'secure' \| 'host'`          | Cookie prefix (`__Secure-` or `__Host-`) |

**Secure Cookie Prefixes:**

```typescript
// __Secure- prefix (requires HTTPS)
response.setCookie('token', 'value', {
  prefix: 'secure'  // ✅ Auto-sets secure: true
});

// __Host- prefix (requires HTTPS, path=/, no domain)
response.setCookie('token', 'value', {
  prefix: 'host'  // ✅ Auto-sets secure, path, removes domain
});
```

<Callout type="warn" title="Cookie Prefix Enforcement">
  Igniter.js **automatically enforces** security requirements for `__Secure-` and `__Host-` cookie prefixes according to RFC 6265bis.
</Callout>

***

## Status Codes

### response.status()

Manually set HTTP status:

```typescript
const action = igniter.mutation({
  handler: async ({ response }) => {
    return response
      .status(418)  // ✅ I'm a teapot
      .json({ message: "I'm a teapot" });
  }
});
```

**Common Status Codes:**

| Code | Method           | Description  |
| ---- | ---------------- | ------------ |
| 200  | `success()`      | OK           |
| 201  | `created()`      | Created      |
| 204  | `noContent()`    | No Content   |
| 400  | `badRequest()`   | Bad Request  |
| 401  | `unauthorized()` | Unauthorized |
| 403  | `forbidden()`    | Forbidden    |
| 404  | `notFound()`     | Not Found    |
| 302  | `redirect()`     | Redirect     |

***

## Real-Time Streaming (SSE)

### response.stream()

Create Server-Sent Events streams for real-time updates:

```typescript
const liveNotifications = igniter.query({
  path: '/notifications/live',
  handler: async ({ response }) => {
    return response.stream({
      channelId: 'notifications:live',
      
      // Optional: send data immediately on connection
      initialData: {
        status: 'connected',
        timestamp: new Date().toISOString()
      },
      
      // Optional: filter messages
      filter: (msg) => msg.data.priority === 'high',
      
      // Optional: transform messages before sending
      transform: (msg) => ({
        ...msg,
        data: { ...msg.data, seen: false }
      })
    });
  }
});
```

**Publishing Events:**

```typescript
import { SSEProcessor } from '@igniter-js/core';

// From anywhere in your app
SSEProcessor.publishEvent({
  channel: 'notifications:live',
  type: 'notification',
  data: {
    id: '123',
    message: 'New order received',
    priority: 'high'
  }
});
```

**Client Connection:**

```typescript
// Client receives connection info
const result = await client.notifications.live.query();

// result.data contains:
// {
//   type: 'stream',
//   channelId: 'notifications:live',
//   connectionInfo: {
//     endpoint: '/api/v1/sse/events',
//     params: { channels: 'notifications:live' }
//   }
// }

// Connect to SSE endpoint
const eventSource = new EventSource(
  `${result.data.connectionInfo.endpoint}?channels=${result.data.connectionInfo.params.channels}`
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('New notification:', data);
};
```

<Callout type="info" title="SSE Architecture">
  Igniter.js uses a **centralized SSE endpoint** (`/api/v1/sse/events`) for all real-time streams. Actions return connection information instead of creating individual SSE endpoints.
</Callout>

***

## Cache Revalidation

### response.revalidate()

Invalidate client-side cache for specific queries:

```typescript
const createPost = igniter.mutation({
  path: '/posts',
  method: 'POST',
  body: CreatePostSchema,
  handler: async ({ request, response, context }) => {
    const post = await context.db.posts.create({
      data: request.body
    });
    
    // ✅ Invalidate 'posts' query on all clients
    return response
      .revalidate(['posts', 'dashboard'])
      .created({ post });
  }
});
```

**With Scoped Revalidation:**

```typescript
const updatePost = igniter.mutation({
  path: '/posts/:id' as const,
  method: 'PATCH',
  handler: async ({ request, response, context }) => {
    const post = await context.db.posts.update({
      where: { id: request.params.id },
      data: request.body
    });
    
    // ✅ Revalidate only for specific tenant
    return response
      .revalidate(['posts', 'user-posts'], async (ctx) => {
        return [`tenant:${ctx.tenantId}`];
      })
      .success({ post });
  }
});
```

**Revalidation Options:**

| Option      | Type                 | Description                                |
| ----------- | -------------------- | ------------------------------------------ |
| `queryKeys` | `string \| string[]` | Query keys to invalidate                   |
| `data`      | `any`                | Optional data to send with revalidation    |
| `broadcast` | `boolean`            | Broadcast to all clients (default: `true`) |
| `scopes`    | `ScopeResolver`      | Function returning scope IDs               |

<Callout type="success" title="Real-Time Cache Updates">
  When you call `response.revalidate()`, Igniter.js automatically notifies all connected clients via SSE to refetch invalidated queries!
</Callout>

***

## Advanced Response Patterns

### Chaining Methods

All response methods are chainable:

```typescript
const action = igniter.mutation({
  handler: async ({ response }) => {
    return response
      .status(201)
      .setHeader('X-Request-ID', 'abc123')
      .setCookie('session', 'token', { httpOnly: true })
      .revalidate(['users'])
      .created({ user });
  }
});
```

### Conditional Responses

```typescript
const getPost = igniter.query({
  path: '/posts/:id' as const,
  handler: async ({ request, response, context }) => {
    const post = await context.db.posts.findUnique({
      where: { id: request.params.id }
    });
    
    if (!post) {
      return response.notFound('Post not found');
    }
    
    if (post.published === false && post.authorId !== context.user?.id) {
      return response.forbidden('This post is not published');
    }
    
    return response.success({ post });
  }
});
```

### Multiple Cookies

```typescript
const login = igniter.mutation({
  handler: async ({ response }) => {
    return response
      .setCookie('accessToken', 'token1', { maxAge: 900 })    // 15 min
      .setCookie('refreshToken', 'token2', { maxAge: 604800 }) // 7 days
      .setCookie('userPrefs', 'theme=dark', { maxAge: 31536000 }) // 1 year
      .success({ message: 'Logged in' });
  }
});
```

***

## Error Response Structure

All error responses follow this structure:

```json
{
  "data": null,
  "error": {
    "code": "ERR_NOT_FOUND",
    "message": "User not found",
    "data": {
      "userId": "123"
    }
  }
}
```

**Success Response Structure:**

```json
{
  "data": {
    "user": {
      "id": "123",
      "name": "John"
    }
  },
  "error": null
}
```

<Callout type="info" title="Discriminated Union">
  The `IgniterResponse` type is a **discriminated union**: either `data` is present (and `error` is `null`), or `error` is present (and `data` is `null`). Never both!
</Callout>

***

## Best Practices

### 1. Use Semantic Response Methods

```typescript
// ✅ Good - Clear intent
return response.created({ user });

// ❌ Bad - Less clear
return response.status(201).json({ user });
```

### 2. Set Cookies Securely

```typescript
// ✅ Good - Secure by default
return response.setCookie('session', token, {
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'strict'
});

// ❌ Bad - Insecure
return response.setCookie('session', token);
```

### 3. Provide Meaningful Error Messages

```typescript
// ✅ Good - Helpful message
return response.notFound(`User with ID "${request.params.id}" not found`);

// ❌ Bad - Generic message
return response.notFound();
```

### 4. Use Revalidation for Mutations

```typescript
// ✅ Good - Auto-update clients
return response
  .revalidate(['posts'])
  .created({ post });

// ❌ Bad - Clients don't know data changed
return response.created({ post });
```

***

## Common Patterns

### CRUD Operations

```typescript
const postController = igniter.controller({
  path: '/posts',
  actions: {
    // List
    list: igniter.query({
      handler: async ({ response }) => {
        const posts = await db.posts.findMany();
        return response.success({ posts });
      }
    }),
    
    // Get
    get: igniter.query({
      path: '/:id' as const,
      handler: async ({ request, response }) => {
        const post = await db.posts.findUnique({
          where: { id: request.params.id }
        });
        
        if (!post) return response.notFound();
        return response.success({ post });
      }
    }),
    
    // Create
    create: igniter.mutation({
      method: 'POST',
      body: CreatePostSchema,
      handler: async ({ request, response }) => {
        const post = await db.posts.create({ data: request.body });
        return response.revalidate(['posts']).created({ post });
      }
    }),
    
    // Update
    update: igniter.mutation({
      path: '/:id' as const,
      method: 'PATCH',
      body: UpdatePostSchema,
      handler: async ({ request, response }) => {
        const post = await db.posts.update({
          where: { id: request.params.id },
          data: request.body
        });
        return response.revalidate(['posts']).success({ post });
      }
    }),
    
    // Delete
    delete: igniter.mutation({
      path: '/:id' as const,
      method: 'DELETE',
      handler: async ({ request, response }) => {
        await db.posts.delete({ where: { id: request.params.id } });
        return response.revalidate(['posts']).noContent();
      }
    })
  }
});
```

### Authentication Flow

```typescript
const authController = igniter.controller({
  path: '/auth',
  actions: {
    login: igniter.mutation({
      path: '/login',
      method: 'POST',
      body: LoginSchema,
      handler: async ({ request, response }) => {
        const { email, password } = request.body;
        
        const user = await db.users.findUnique({ where: { email } });
        
        if (!user) {
          return response.unauthorized('Invalid credentials');
        }
        
        const valid = await verifyPassword(password, user.passwordHash);
        
        if (!valid) {
          return response.unauthorized('Invalid credentials');
        }
        
        const token = generateToken(user);
        
        return response
          .setCookie('session', token, {
            httpOnly: true,
            secure: true,
            sameSite: 'strict',
            maxAge: 3600
          })
          .success({ user: { id: user.id, name: user.name, email: user.email } });
      }
    }),
    
    logout: igniter.mutation({
      path: '/logout',
      method: 'POST',
      handler: async ({ response }) => {
        return response
          .setCookie('session', '', { maxAge: 0 })
          .success({ message: 'Logged out' });
      }
    })
  }
});
```

***

## Next Steps

<Cards>
  <Card title="Error Handling" href="/docs/error-handling">
    Handle errors gracefully in actions
  </Card>

  <Card title="Validation" href="/docs/validation">
    Validate request data with schemas
  </Card>

  <Card title="Client" href="/docs/client">
    Use responses on the client-side
  </Card>

  <Card title="Testing" href="/docs/testing">
    Test response types
  </Card>
</Cards>


---

# Validation

> Master input validation in Igniter.js using Zod, Valibot, Yup, or any StandardSchemaV1-compliant library for type-safe request handling.
URL: https://igniterjs.com/docs/core/validation

## Overview

**Validation** in Igniter.js ensures that incoming data (request body, query parameters) matches your expected schema before reaching your action handler. This prevents bugs, improves security, and provides automatic type inference.

```typescript
import { igniter } from '@/igniter';
import { z } from 'zod';

const CreateUserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  age: z.number().int().min(18)
});

const userController = igniter.controller({
  path: '/users',
  actions: {
    create: igniter.mutation({
      path: '/',
      method: 'POST',
      body: CreateUserSchema,  // ✅ Auto-validates and types request.body
      handler: async ({ request, response }) => {
        // ✅ request.body is fully typed and validated!
        const { name, email, age } = request.body;
        
        const user = await db.users.create({ data: { name, email, age } });
        return response.created({ user });
      }
    })
  }
});
```

<Callout type="success" title="Automatic Type Inference">
  When you provide a validation schema, TypeScript **automatically infers** the type of `request.body` or `request.query`. No manual type annotations needed!
</Callout>

***

## StandardSchemaV1

Igniter.js uses the **StandardSchemaV1** interface, which means it works with any validation library that implements this standard:

* ✅ **Zod** (most popular)
* ✅ **Valibot** (lightweight alternative)
* ✅ **Yup** (with adapter)
* ✅ **ArkType**
* ✅ Any custom schema implementing StandardSchemaV1

<Callout type="info" title="What is StandardSchemaV1?">
  StandardSchemaV1 is a universal interface for validation libraries. It allows Igniter.js to work with multiple validation libraries without being tied to any specific one.
</Callout>

***

## Body Validation

Validate request bodies for POST, PUT, PATCH requests:

### Basic Body Validation

```typescript
import { z } from 'zod';

const CreatePostSchema = z.object({
  title: z.string().min(3).max(100),
  content: z.string().min(10),
  published: z.boolean().default(false)
});

const postController = igniter.controller({
  path: '/posts',
  actions: {
    create: igniter.mutation({
      path: '/',
      method: 'POST',
      body: CreatePostSchema,
      handler: async ({ request, context, response }) => {
        // ✅ request.body is typed as:
        // {
        //   title: string;
        //   content: string;
        //   published: boolean;
        // }
        
        const post = await context.db.posts.create({
          data: request.body
        });
        
        return response.created({ post });
      }
    })
  }
});
```

### Nested Objects

```typescript
const CreateUserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  profile: z.object({
    bio: z.string().optional(),
    avatar: z.string().url().optional(),
    social: z.object({
      twitter: z.string().optional(),
      github: z.string().optional()
    }).optional()
  }),
  settings: z.object({
    newsletter: z.boolean().default(true),
    notifications: z.boolean().default(true)
  })
});

// Usage
const userController = igniter.controller({
  path: '/users',
  actions: {
    create: igniter.mutation({
      method: 'POST',
      body: CreateUserSchema,
      handler: async ({ request, response }) => {
        // ✅ Fully typed nested access
        const { name, email, profile, settings } = request.body;
        console.log(profile.social?.twitter);
        console.log(settings.newsletter);
      }
    })
  }
});
```

### Arrays

```typescript
const CreatePostSchema = z.object({
  title: z.string(),
  content: z.string(),
  tags: z.array(z.string()).min(1).max(5),  // 1-5 tags
  categories: z.array(z.enum(['tech', 'design', 'business'])),
  coAuthors: z.array(z.object({
    name: z.string(),
    email: z.string().email()
  })).optional()
});

// Usage
const handler = async ({ request }) => {
  // ✅ request.body.tags is string[]
  // ✅ request.body.categories is ('tech' | 'design' | 'business')[]
  // ✅ request.body.coAuthors is { name: string; email: string }[] | undefined
};
```

***

## Query Validation

Validate URL query parameters:

### Basic Query Validation

```typescript
const SearchSchema = z.object({
  q: z.string().min(1),
  limit: z.coerce.number().min(1).max(100).default(20),
  offset: z.coerce.number().min(0).default(0)
});

const productController = igniter.controller({
  path: '/products',
  actions: {
    search: igniter.query({
      path: '/search',
      query: SearchSchema,
      handler: async ({ request, context, response }) => {
        // ✅ request.query is typed as:
        // {
        //   q: string;
        //   limit: number;
        //   offset: number;
        // }
        
        const { q, limit, offset } = request.query;
        
        const products = await context.db.products.findMany({
          where: { name: { contains: q } },
          take: limit,
          skip: offset
        });
        
        return response.success({ products });
      }
    })
  }
});

// Usage: GET /products/search?q=laptop&limit=10&offset=0
```

<Callout type="warn" title="Use z.coerce for Query Params">
  Query parameters come as **strings** from URLs. Use `z.coerce.number()`, `z.coerce.boolean()`, etc. to automatically convert them!
</Callout>

### Advanced Query Validation

```typescript
const ProductSearchSchema = z.object({
  q: z.string().min(1),
  category: z.enum(['electronics', 'clothing', 'books']).optional(),
  minPrice: z.coerce.number().min(0).optional(),
  maxPrice: z.coerce.number().min(0).optional(),
  sortBy: z.enum(['price', 'date', 'popularity']).default('date'),
  order: z.enum(['asc', 'desc']).default('desc'),
  inStock: z.coerce.boolean().optional(),
  tags: z.string().transform(val => val.split(',')).optional()  // "tag1,tag2" → ["tag1", "tag2"]
});

const handler = async ({ request }) => {
  const { q, category, minPrice, maxPrice, sortBy, order, inStock, tags } = request.query;
  
  // ✅ All types are inferred correctly:
  // q: string
  // category: 'electronics' | 'clothing' | 'books' | undefined
  // minPrice: number | undefined
  // sortBy: 'price' | 'date' | 'popularity'
  // tags: string[] | undefined
};
```

***

## Validation Errors

When validation fails, Igniter.js automatically returns a `400 Bad Request` with detailed error information:

### Example Validation Error

Request:

```json
POST /users
{
  "name": "J",
  "email": "invalid-email",
  "age": 15
}
```

Response (400 Bad Request):

```json
{
  "error": "Validation failed",
  "issues": [
    {
      "path": ["name"],
      "message": "String must contain at least 2 character(s)"
    },
    {
      "path": ["email"],
      "message": "Invalid email"
    },
    {
      "path": ["age"],
      "message": "Number must be greater than or equal to 18"
    }
  ]
}
```

***

## Common Validation Patterns

### Optional Fields

```typescript
const UpdateUserSchema = z.object({
  name: z.string().min(2).optional(),
  email: z.string().email().optional(),
  bio: z.string().max(500).optional()
});

// Or use .partial() to make all fields optional
const UpdateUserSchema2 = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  bio: z.string().max(500)
}).partial();
```

### Default Values

```typescript
const CreatePostSchema = z.object({
  title: z.string(),
  content: z.string(),
  published: z.boolean().default(false),     // ✅ Defaults to false if not provided
  views: z.number().default(0),
  tags: z.array(z.string()).default([])
});
```

### Transformations

```typescript
const CreateUserSchema = z.object({
  email: z.string().email().transform(val => val.toLowerCase()),  // ✅ Auto-lowercase
  name: z.string().transform(val => val.trim()),                  // ✅ Auto-trim
  age: z.string().transform(val => parseInt(val, 10))             // ✅ Convert to number
});
```

### Custom Refinements

```typescript
const CreateUserSchema = z.object({
  password: z.string().min(8),
  confirmPassword: z.string()
}).refine(data => data.password === data.confirmPassword, {
  message: "Passwords don't match",
  path: ["confirmPassword"]
});
```

### Conditional Validation

```typescript
const CreateOrderSchema = z.object({
  items: z.array(z.object({
    productId: z.string(),
    quantity: z.number().min(1)
  })),
  paymentMethod: z.enum(['credit_card', 'paypal', 'bank_transfer']),
  creditCard: z.object({
    number: z.string(),
    cvv: z.string(),
    expiryDate: z.string()
  }).optional()
}).refine(
  data => {
    // Require credit card details if payment method is credit card
    if (data.paymentMethod === 'credit_card') {
      return !!data.creditCard;
    }
    return true;
  },
  {
    message: "Credit card details are required for credit card payments",
    path: ["creditCard"]
  }
);
```

***

## Combining Body and Query Validation

You can validate both at the same time:

```typescript
const CreateUserSchema = z.object({
  name: z.string(),
  email: z.string().email()
});

const InviteQuerySchema = z.object({
  inviteCode: z.string().length(8)
});

const userController = igniter.controller({
  path: '/users',
  actions: {
    createWithInvite: igniter.mutation({
      path: '/',
      method: 'POST',
      body: CreateUserSchema,      // ✅ Validates body
      query: InviteQuerySchema,    // ✅ Validates query
      handler: async ({ request, response }) => {
        // ✅ Both request.body and request.query are typed and validated
        const { name, email } = request.body;
        const { inviteCode } = request.query;
        
        // Verify invite code
        const invite = await db.invites.findUnique({
          where: { code: inviteCode }
        });
        
        if (!invite) {
          return response.badRequest({ message: 'Invalid invite code' });
        }
        
        // Create user
        const user = await db.users.create({ data: { name, email } });
        return response.created({ user });
      }
    })
  }
});

// Usage: POST /users?inviteCode=ABC12345
// Body: { "name": "John", "email": "john@example.com" }
```

***

## Using Valibot

Valibot is a lightweight alternative to Zod with similar API:

```typescript
import * as v from 'valibot';

const CreateUserSchema = v.object({
  name: v.pipe(v.string(), v.minLength(2)),
  email: v.pipe(v.string(), v.email()),
  age: v.pipe(v.number(), v.integer(), v.minValue(18))
});

const userController = igniter.controller({
  path: '/users',
  actions: {
    create: igniter.mutation({
      path: '/',
      method: 'POST',
      body: CreateUserSchema,  // ✅ Works the same as Zod!
      handler: async ({ request, response }) => {
        // ✅ request.body is fully typed
        const { name, email, age } = request.body;
      }
    })
  }
});
```

***

## Schema Reusability

### Extract Common Schemas

```typescript
// schemas/user.schema.ts
export const EmailSchema = z.string().email();
export const PasswordSchema = z.string().min(8).max(100);
export const NameSchema = z.string().min(2).max(50);

export const UserSchema = z.object({
  name: NameSchema,
  email: EmailSchema,
  password: PasswordSchema
});

export const CreateUserSchema = UserSchema;
export const UpdateUserSchema = UserSchema.partial();
export const LoginSchema = UserSchema.pick({ email: true, password: true });
```

### Compose Schemas

```typescript
const AddressSchema = z.object({
  street: z.string(),
  city: z.string(),
  state: z.string(),
  zip: z.string()
});

const UserSchema = z.object({
  name: z.string(),
  email: z.string().email()
});

const UserWithAddressSchema = UserSchema.extend({
  address: AddressSchema
});

// Or merge
const UserWithAddressSchema2 = UserSchema.merge(
  z.object({ address: AddressSchema })
);
```

### Inheritance

```typescript
const BaseEntitySchema = z.object({
  id: z.string(),
  createdAt: z.date(),
  updatedAt: z.date()
});

const UserSchema = BaseEntitySchema.extend({
  name: z.string(),
  email: z.string().email()
});

const PostSchema = BaseEntitySchema.extend({
  title: z.string(),
  content: z.string(),
  authorId: z.string()
});
```

***

## Best Practices

### 1. Use Descriptive Error Messages

```typescript
const CreateUserSchema = z.object({
  email: z.string().email('Please provide a valid email address'),
  password: z.string()
    .min(8, 'Password must be at least 8 characters')
    .max(100, 'Password must not exceed 100 characters')
    .regex(/[A-Z]/, 'Password must contain at least one uppercase letter')
    .regex(/[0-9]/, 'Password must contain at least one number'),
  age: z.number()
    .int('Age must be a whole number')
    .min(18, 'You must be at least 18 years old')
    .max(120, 'Age seems unrealistic')
});
```

### 2. Extract Schemas into Separate Files

```typescript
// ✅ Good - Organized and reusable
// schemas/user.schema.ts
export const CreateUserSchema = z.object({ /* ... */ });
export const UpdateUserSchema = z.object({ /* ... */ });

// features/users/user.controller.ts
import { CreateUserSchema, UpdateUserSchema } from '@/schemas/user.schema';
```

### 3. Use z.coerce for URL Parameters

```typescript
// ✅ Good - Auto-converts strings to numbers
const PaginationSchema = z.object({
  page: z.coerce.number().min(1).default(1),
  limit: z.coerce.number().min(1).max(100).default(20)
});

// ❌ Bad - Will fail because URL params are strings
const PaginationSchema = z.object({
  page: z.number().min(1).default(1),  // ❌ "1" is not a number!
  limit: z.number().min(1).max(100).default(20)
});
```

### 4. Validate Early

```typescript
// ✅ Good - Validation happens before handler
const action = igniter.mutation({
  body: CreateUserSchema,
  handler: async ({ request }) => {
    // request.body is already validated
  }
});

// ❌ Bad - Manual validation in handler
const action = igniter.mutation({
  handler: async ({ request }) => {
    const result = CreateUserSchema.safeParse(request.body);
    if (!result.success) {
      // Handle errors manually...
    }
  }
});
```

***

## Advanced Validation

### Async Refinements

```typescript
const CreateUserSchema = z.object({
  email: z.string().email()
}).refine(
  async (data) => {
    // Check if email already exists
    const existing = await db.users.findUnique({
      where: { email: data.email }
    });
    return !existing;
  },
  {
    message: "Email already in use",
    path: ["email"]
  }
);
```

### Custom Validators

```typescript
const isValidCreditCard = (cardNumber: string) => {
  // Luhn algorithm
  return /* validation logic */;
};

const PaymentSchema = z.object({
  cardNumber: z.string().refine(isValidCreditCard, {
    message: "Invalid credit card number"
  }),
  cvv: z.string().length(3).regex(/^\d{3}$/, "CVV must be 3 digits"),
  expiryDate: z.string().regex(/^\d{2}\/\d{2}$/, "Format: MM/YY")
});
```

***

## Next Steps

<Cards>
  <Card title="Actions" href="/docs/actions">
    Use validation in queries and mutations
  </Card>

  <Card title="Error Handling" href="/docs/error-handling">
    Handle validation errors gracefully
  </Card>

  <Card title="Response Types" href="/docs/response-types">
    Return proper error responses
  </Card>

  <Card title="Testing" href="/docs/testing">
    Test validation logic
  </Card>
</Cards>


---

# Bun

> Build blazing-fast, type-safe APIs with Igniter.js and Bun, the all-in-one JavaScript runtime.
URL: https://igniterjs.com/docs/core/bun

Bun is a modern JavaScript runtime that's incredibly fast, with built-in bundling, testing, and package management. When combined with Igniter.js, you get exceptional performance with zero configuration—no build tools, no bundlers, just pure speed and developer happiness.

This guide shows you how to build production-ready APIs with Bun and Igniter.js. You'll experience Bun's lightning-fast startup times, instant hot reload, and native TypeScript support, all while maintaining Igniter.js's type-safe controllers and automatic API documentation.

<Callout type="success" title="Maximum Performance">
  Bun + Igniter.js delivers incredible performance out of the box. Bun's runtime is 4x faster than Node.js, with instant startup and built-in TypeScript support.
</Callout>

***

## Quick Start

The fastest way to start is using the official CLI with Bun's native speed:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest init
    ```
  </Tab>
</Tabs>

Your API runs at `http://localhost:3000/api/v1`, and interactive docs at `http://localhost:3000/api/v1/docs` 🚀

### Direct Command

If you prefer to skip the interactive prompts, you can specify your project name and framework directly:

#### For REST API

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="direct-command-rest">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest init my-bun-api --framework bun-rest-api
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest init my-bun-api --framework bun-rest-api
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest init my-bun-api --framework bun-rest-api
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest init my-bun-api --framework bun-rest-api
    ```
  </Tab>
</Tabs>

#### For Fullstack React App

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="direct-command-react">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest init my-bun-app --framework bun-react-app
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest init my-bun-app --framework bun-react-app
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest init my-bun-app --framework bun-react-app
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest init my-bun-app --framework bun-react-app
    ```
  </Tab>
</Tabs>

These commands will create Bun projects with all Igniter.js features pre-configured.

***

## Manual Setup

<Card title="Complete Bun Setup Guide">
  <Steps>
    <Step>
      ### Prerequisites

      Before you begin, ensure you have:

      * **Bun** 1.0+ ([install here](https://bun.sh))
      * Basic knowledge of TypeScript
    </Step>

    <Step>
      ### Install Dependencies

      Install Igniter.js and Zod for schema validation:

      ```bash
      bun add @igniter-js/core zod
      ```

      Bun has native TypeScript support—no additional type packages or build tools needed!
    </Step>

    <Step>
      ### Define Application Context

      The context defines dependencies available throughout your API. Create `src/igniter.context.ts`:

      ```typescript title="src/igniter.context.ts"
      /**
       * Application Context Type
       * Defines what dependencies are available to all API handlers
       */
      export interface AppContext {
        // Add your dependencies here, e.g.:
        // db: Database
        // cache: RedisClient
      }

      /**
       * Context Factory
       * Creates the context instance passed to handlers
       */
      export function createIgniterAppContext(): AppContext {
        return {
          // Initialize dependencies here
        }
      }
      ```
    </Step>

    <Step>
      ### Initialize Igniter.js

      Create the main Igniter instance. Create `src/igniter.ts`:

      ```typescript title="src/igniter.ts"
      import { Igniter } from '@igniter-js/core'
      import { createIgniterAppContext } from './igniter.context'

      export const igniter = Igniter
        .context(createIgniterAppContext())
        .config({
          baseURL: process.env.IGNITER_API_URL || 'http://localhost:3000',
          basePATH: process.env.IGNITER_API_BASE_PATH || '/api/v1',
        })
        .docs({
          info: {
            title: 'My Bun API',
            version: '1.0.0',
            description: 'High-performance API built with Bun and Igniter.js',
          }
        })
        .create()
      ```
    </Step>

    <Step>
      ### Create Your First Controller

      Controllers group related endpoints. Create `src/features/example/controllers/example.controller.ts`:

      ```typescript title="src/features/example/controllers/example.controller.ts"
      import { igniter } from '@/igniter'

      export const exampleController = igniter.controller({
        name: 'Example',
        path: '/example',
        actions: {
          hello: igniter.query({
            path: '/hello',
            handler: async ({ response }) => {
              return response.success({ 
                message: 'Hello from Igniter.js with Bun! ⚡',
                timestamp: new Date().toISOString(),
                runtime: 'Bun'
              })
            },
          }),
        },
      })
      ```

      Create barrel export at `src/features/example/index.ts`:

      ```typescript title="src/features/example/index.ts"
      export * from './controllers/example.controller'
      ```

      This creates `GET /api/v1/example/hello` with fully typed responses.
    </Step>

    <Step>
      ### Create Application Router

      The router assembles all controllers. Create `src/igniter.router.ts`:

      ```typescript title="src/igniter.router.ts"
      import { igniter } from './igniter'
      import { exampleController } from './features/example'

      export const AppRouter = igniter.router({
        controllers: {
          example: exampleController
        }
      })

            export type AppRouterType = typeof AppRouter
      ```
    </Step>

    <Step>
      ### Set Up Bun Server

      Bun has a built-in HTTP server that's incredibly fast. Create `src/index.ts`:

      ```typescript title="src/index.ts"
      import { serve } from 'bun'
      import { AppRouter } from './igniter.router'

      const IGNITER_API_BASE_PATH = process.env.IGNITER_API_BASE_PATH || '/api/v1/'

      const server = serve({
        routes: {
          // Mount Igniter.js router
          [IGNITER_API_BASE_PATH + '*']: AppRouter.handler,
        },
      })

      console.log(`🚀 Server running at ${server.url}`)
      ```

      Bun's native routing is simple and performant—no framework overhead needed!

      ### Step 7: Add Development Scripts

      Update your `package.json`:

      ```json title="package.json"
      {
        "scripts": {
          "dev": "bun --hot src/index.ts",
          "start": "bun src/index.ts"
        }
      }
      ```

      Now run `bun dev` for instant hot reload! Changes apply in milliseconds.
    </Step>
  </Steps>
</Card>

## Bun-Specific Features

### Native TypeScript

Bun runs TypeScript directly—no transpilation needed:

```typescript
// Just write TypeScript and run it!
import type { User } from './types'

const user: User = { name: 'John' }
```

### Environment Variables

Bun has built-in `.env` support. Create `.env`:

```bash title=".env"
IGNITER_API_BASE_PATH=/api/v1/
IGNITER_API_URL=http://localhost:3000
```

Access them via `Bun.env`:

```typescript
const port = Bun.env.PORT || 3000
```

### Built-in Testing

Bun includes a fast test runner compatible with Jest:

```typescript title="src/features/example/example.test.ts"
import { describe, test, expect } from 'bun:test'
import { api } from '@/igniter.client'

describe('Example Controller', () => {
  test('returns hello message', async () => {
    const result = await api.example.hello.query()
    expect(result.message).toContain('Bun')
  })
})
```

Run tests with `bun test` - it's incredibly fast!

***

## Full-Stack with Bun React

For full-stack applications, use the `bun-react-app` template which includes React:

```typescript title="src/index.tsx" {10}
import { serve } from 'bun'
import { AppRouter } from './igniter.router'
import index from './index.html'

const server = serve({
  routes: {
    // Serve React app for all unmatched routes
    '/*': index,
    
    // Serve API
    '/api/v1/*': AppRouter.handler,
  },
  
  development: Bun.env.NODE_ENV !== 'production' && {
    hmr: true,       // Hot module reload
    console: true,   // Browser console logging
  },
})

console.log(`🚀 Server running at ${server.url}`)
```

This single file serves both your React frontend and Igniter.js API with hot reload!

***

## Type-Safe Client

Create a type-safe client for consuming your API. Create `src/igniter.client.ts`:

```typescript title="src/igniter.client.ts"
import { createIgniterClient } from '@igniter-js/core/client'
import type { AppRouterType } from './igniter.router'

export const api = createIgniterClient<AppRouterType>({
  baseURL: Bun.env.IGNITER_API_URL || 'http://localhost:3000',
  basePATH: Bun.env.IGNITER_API_BASE_PATH || '/api/v1',
  router: () => require('./igniter.router').AppRouter,
})

export type ApiClient = typeof api
```

Use it anywhere:

```typescript
// Fully typed, instant autocomplete
const { message, runtime } = await api.example.hello.query()
```

***

## Generating Schema and Docs

For full-stack Bun projects (Bun + React), you'll need to generate the client schema whenever you modify your API.

### When to Generate Schema

<Callout type="error">
  **Critical:** You MUST run schema generation BEFORE using the client in your frontend. The client depends on the generated schema to function correctly.
</Callout>

<Callout type="info">
  Run this command whenever you modify your API structure (add/remove/modify controllers or actions) OR before using the client for the first time.
</Callout>

### Generate Schema

Run this command whenever you make changes to your API structure:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="generate-schema">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest generate schema
    ```
  </Tab>
</Tabs>

This creates:

* `src/igniter.schema.ts` - Type-safe schema for client-side usage
* `src/docs/openapi.json` - OpenAPI 3.0 specification

### Generate OpenAPI Documentation

To generate or update the OpenAPI specification and interactive documentation:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="generate-docs">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest generate docs
    ```
  </Tab>
</Tabs>

***

## Igniter Studio (API Playground)

Igniter.js includes an interactive API playground called **Igniter Studio**. It's automatically available at `/api/v1/docs` when you configure the `.docs()` method.

To access it:

1. Start your dev server: `bun dev`
2. Navigate to `http://localhost:3000/api/v1/docs`
3. You'll see an interactive interface where you can:
   * Browse all API endpoints
   * View request/response schemas
   * Test endpoints directly
   * See auto-generated examples

The playground updates automatically as you add endpoints.

***

## Performance Tips

### Use Bun's Native APIs

Bun provides optimized native APIs for common tasks:

```typescript
// File I/O (much faster than Node.js fs)
const file = Bun.file('data.json')
const data = await file.json()

// Hashing
const hash = Bun.hash('sha256', 'data')

// Environment variables
const secret = Bun.env.SECRET_KEY
```

### Database with Bun

Bun works great with Prisma, the recommended ORM for Igniter.js:

```typescript
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()
```

***

## Project Structure

Here's the recommended structure:

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="features">
      <Folder name="example">
        <Folder name="controllers">
          <File name="example.controller.ts" />
        </Folder>

        <File name="index.ts" />
      </Folder>
    </Folder>

    <Folder name="docs">
      <File name="openapi.json" />
    </Folder>

    <File name="index.ts" />

    <File name="igniter.ts" />

    <File name="igniter.context.ts" />

    <File name="igniter.router.ts" />

    <File name="igniter.client.ts" />

    <File name="igniter.schema.ts" />
  </Folder>

  <File name="package.json" />

  <File name="tsconfig.json" />

  <File name="bunfig.toml" />
</Files>

***

## Next Steps

<Cards>
  <Card title="Core Concepts" href="/docs/builder">
    Learn about Builder, Router, and Controllers
  </Card>

  <Card title="Actions" href="/docs/actions">
    Create queries and mutations with validation
  </Card>

  <Card title="Database" href="/docs/database">
    Integrate Prisma or Drizzle ORM
  </Card>
</Cards>


---

# Deno

> Build secure, type-safe APIs with Igniter.js and Deno, the modern JavaScript runtime built for security and productivity.
URL: https://igniterjs.com/docs/core/deno

Deno is a modern JavaScript runtime that prioritizes security, developer experience, and web standards. When combined with Igniter.js, you get a secure-by-default environment with native TypeScript support, built-in testing, and automatic code formatting—all without configuration.

This guide shows you how to build production-ready APIs with Deno and Igniter.js. You'll experience Deno's security model with granular permissions, standard library utilities, and native TypeScript execution, all while maintaining Igniter.js's type-safe controllers and automatic API documentation.

<Callout type="info" title="Secure by Default">
  Deno + Igniter.js provides security-first development. Deno requires explicit permissions for file system, network, and environment access—perfect for production deployments.
</Callout>

***

## Quick Start

The fastest way to start is using the official CLI with Deno's native TypeScript support:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest init
    ```
  </Tab>
</Tabs>

Your API runs at `http://localhost:8000/api/v1`, and interactive docs at `http://localhost:8000/api/v1/docs` 🚀

***

## Manual Setup

<Card title="Complete Deno Setup Guide">
  <Steps>
    <Step>
      ### Prerequisites

      Before you begin, ensure you have:

      * **Deno** 1.40+ ([install here](https://deno.land))
      * Basic knowledge of TypeScript
    </Step>

    <Step>
      ### Initialize Deno Project

      Create a new directory and initialize with `deno.json`:

      ```json title="deno.json"
      {
        "tasks": {
          "dev": "deno run --allow-net --allow-env --allow-read --watch src/index.ts",
          "start": "deno run --allow-net --allow-env --allow-read src/index.ts"
        },
        "compilerOptions": {
          "lib": ["deno.window"],
          "strict": true
        },
        "imports": {
          "@/": "./src/",
          "@igniter-js/core": "npm:@igniter-js/core@latest",
          "zod": "npm:zod@latest"
        }
      }
      ```

      Deno's import map allows you to use npm packages seamlessly with native Deno modules.
    </Step>

    <Step>
      ### Define Application Context

      The context defines dependencies available throughout your API. Create `src/igniter.context.ts`:

      ```typescript title="src/igniter.context.ts"
      /**
       * Application Context Type
       * Defines what dependencies are available to all API handlers
       */
      export interface AppContext {
        // Add your dependencies here, e.g.:
        // db: Database
        // cache: KvStore
      }

      /**
       * Context Factory
       * Creates the context instance passed to handlers
       */
      export function createIgniterAppContext(): AppContext {
        return {
          // Initialize dependencies here
        }
      }
      ```
    </Step>

    <Step>
      ### Initialize Igniter.js

      Create the main Igniter instance. Create `src/igniter.ts`:

      ```typescript title="src/igniter.ts"
      import { Igniter } from '@igniter-js/core'
      import { createIgniterAppContext } from './igniter.context.ts'

      export const igniter = Igniter
        .context(createIgniterAppContext())
        .config({
          baseURL: Deno.env.get('IGNITER_API_URL') || 'http://localhost:8000',
          basePATH: Deno.env.get('IGNITER_API_BASE_PATH') || '/api/v1',
        })
        .docs({
          info: {
            title: 'My Deno API',
            version: '1.0.0',
            description: 'Secure API built with Deno and Igniter.js',
          }
        })
        .create()
      ```

      Note: Deno uses `Deno.env.get()` for environment variables with explicit `--allow-env` permission.
    </Step>

    <Step>
      ### Create Your First Controller

      Controllers group related endpoints. Create `src/features/example/controllers/example.controller.ts`:

      ```typescript title="src/features/example/controllers/example.controller.ts"
      import { igniter } from '@/igniter.ts'

      export const exampleController = igniter.controller({
        name: 'Example',
        path: '/example',
        actions: {
          hello: igniter.query({
            path: '/hello',
            handler: async ({ response }) => {
              return response.success({ 
                message: 'Hello from Igniter.js with Deno! 🦕',
                timestamp: new Date().toISOString(),
                runtime: 'Deno',
                version: Deno.version.deno
              })
            },
          }),
        },
      })
      ```

      Create barrel export at `src/features/example/index.ts`:

      ```typescript title="src/features/example/index.ts"
      export * from './controllers/example.controller.ts'
      ```

      This creates `GET /api/v1/example/hello` with fully typed responses.
    </Step>

    <Step>
      ### Create Application Router

      The router assembles all controllers. Create `src/igniter.router.ts`:

      ```typescript title="src/igniter.router.ts"
      import { igniter } from './igniter.ts'
      import { exampleController } from './features/example/index.ts'

      export const AppRouter = igniter.router({
        controllers: {
          example: exampleController
        }
      })

            export type AppRouterType = typeof AppRouter
      ```
    </Step>

    <Step>
      ### Set Up Deno Server

      Deno has a built-in HTTP server based on web standards. Create `src/index.ts`:

      ```typescript title="src/index.ts"
      import { serve } from 'https://deno.land/std@0.203.0/http/server.ts'
      import { AppRouter } from './igniter.router.ts'

      const handler = (req: Request) => {
        const url = new URL(req.url)
        const IGNITER_API_BASE_PATH = Deno.env.get('IGNITER_API_BASE_PATH') || '/api/v1'

        // Route to Igniter.js
        if (url.pathname.startsWith(IGNITER_API_BASE_PATH)) {
          return AppRouter.handler(req)
        }

        return new Response('Not Found', { status: 404 })
      }

      const port = 8000

      serve(handler, { port })

      console.log(`🚀 Server running at http://localhost:${port}/`)
      ```

      Deno's `serve` function uses the standard `Request` and `Response` APIs—no framework needed!

      ### Step 7: Run with Permissions

      Deno requires explicit permissions. Run your server:

      ```bash
      # Development with auto-reload
      deno task dev

      # Or run directly
      deno run --allow-net --allow-env --allow-read --watch src/index.ts
      ```

      Permissions explained:

      * `--allow-net`: Network access for HTTP server
      * `--allow-env`: Read environment variables
      * `--allow-read`: Read files (for static assets, configs)
      * `--watch`: Auto-reload on file changes
    </Step>
  </Steps>
</Card>

## Deno-Specific Features

### Native TypeScript

Deno runs TypeScript natively—no build step required. File extensions are mandatory:

```typescript
// Always include .ts extension
import { igniter } from './igniter.ts'
import type { User } from './types.ts'
```

### Environment Variables

Create `.env` file and load with `--env` flag:

```bash title=".env"
IGNITER_API_BASE_PATH=/api/v1
IGNITER_API_URL=http://localhost:8000
DATABASE_URL=postgresql://localhost/mydb
```

Access via `Deno.env.get()`:

```typescript
const dbUrl = Deno.env.get('DATABASE_URL')
```

Or use the `--env` flag:

```bash
deno run --env --allow-net --allow-env src/index.ts
```

### Deno KV (Built-in Database)

Deno includes a built-in key-value database:

```typescript title="src/igniter.context.ts"
export async function createIgniterAppContext() {
  const kv = await Deno.openKv()
  
  return {
    db: kv
  }
}
```

Use it in controllers:

```typescript
const result = await context.db.get(['users', userId])
await context.db.set(['users', userId], userData)
```

### Standard Library

Deno's standard library provides utilities without npm:

```typescript
// File system
import { ensureDir } from 'https://deno.land/std@0.203.0/fs/mod.ts'

// HTTP server
import { serve } from 'https://deno.land/std@0.203.0/http/server.ts'

// Testing
import { assertEquals } from 'https://deno.land/std@0.203.0/assert/mod.ts'
```

***

## Type-Safe Client

Create a type-safe client for consuming your API. Create `src/igniter.client.ts`:

```typescript title="src/igniter.client.ts"
import { createIgniterClient } from '@igniter-js/core/client'
import type { AppRouterType } from './igniter.router.ts'

export const api = createIgniterClient<AppRouterType>({
  baseURL: Deno.env.get('IGNITER_API_URL') || 'http://localhost:8000',
  basePATH: Deno.env.get('IGNITER_API_BASE_PATH') || '/api/v1',
  router: () => {
    // Dynamic import for Deno
    return import('./igniter.router.ts').then(m => m.AppRouter)
  },
})

export type ApiClient = typeof api
```

Use it anywhere:

```typescript
// Fully typed, secure by default
const { message, version } = await api.example.hello.query()
```

***

## Testing with Deno

Deno has built-in testing—no additional packages needed:

```typescript title="src/features/example/example.test.ts"
import { assertEquals } from 'https://deno.land/std@0.203.0/assert/mod.ts'
import { api } from '@/igniter.client.ts'

Deno.test('Example controller returns hello message', async () => {
  const result = await api.example.hello.query()
  
  assertEquals(result.runtime, 'Deno')
  assertEquals(typeof result.version, 'string')
})
```

Run tests:

```bash
deno test --allow-net --allow-env
```

***

## Igniter Studio (API Playground)

Igniter.js includes an interactive API playground called **Igniter Studio**. It's automatically available at `/api/v1/docs` when you configure the `.docs()` method.

To access it:

1. Start your dev server: `deno task dev`
2. Navigate to `http://localhost:8000/api/v1/docs`
3. You'll see an interactive interface where you can:
   * Browse all API endpoints
   * View request/response schemas
   * Test endpoints directly
   * See auto-generated examples

The playground updates automatically as you add endpoints.

***

## Production Deployment

### Deno Deploy

Deploy to Deno's edge network with zero configuration:

```bash
# Install Deno Deploy CLI
deno install --allow-all --no-check -r -f https://deno.land/x/deploy/deployctl.ts

# Deploy your project
deployctl deploy --project=my-api src/index.ts
```

### Docker

Create a `Dockerfile`:

```dockerfile
FROM denoland/deno:1.40.0

WORKDIR /app
COPY . .

RUN deno cache src/index.ts

EXPOSE 8000

CMD ["deno", "run", "--allow-net", "--allow-env", "--allow-read", "src/index.ts"]
```

***

## Project Structure

Here's the recommended structure:

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="features">
      <Folder name="example">
        <Folder name="controllers">
          <File name="example.controller.ts" />
        </Folder>

        <File name="index.ts" />
      </Folder>
    </Folder>

    <Folder name="docs">
      <File name="openapi.json" />
    </Folder>

    <File name="index.ts" />

    <File name="igniter.ts" />

    <File name="igniter.context.ts" />

    <File name="igniter.router.ts" />

    <File name="igniter.client.ts" />

    <File name="igniter.schema.ts" />
  </Folder>

  <File name="deno.json" />

  <File name=".env" />
</Files>

***

## Next Steps

<Cards>
  <Card title="Core Concepts" href="/docs/builder">
    Learn about Builder, Router, and Controllers
  </Card>

  <Card title="Actions" href="/docs/actions">
    Create queries and mutations with validation
  </Card>

  <Card title="Deno KV" href="/docs/storage">
    Use Deno's built-in database
  </Card>
</Cards>


---

# Express

> Build type-safe REST APIs with Igniter.js and Express.js, the minimal and flexible Node.js web framework.
URL: https://igniterjs.com/docs/core/express

Express.js is the most popular Node.js web framework, known for its minimalist approach and robust middleware ecosystem. When combined with Igniter.js, you maintain Express's simplicity and flexibility while gaining end-to-end type safety, automatic schema generation, and a modern API design experience.

This guide shows you how to integrate Igniter.js with Express to build production-ready REST APIs. You'll learn how to leverage Express's mature ecosystem (middleware, routing, error handling) alongside Igniter.js's type-safe controllers and automatic documentation.

<Callout type="info" title="Perfect for REST APIs">
  Express + Igniter.js is ideal for building traditional REST APIs, microservices, and backends that need Express's mature middleware ecosystem.
</Callout>

***

## Quick Start

The fastest way to start is using the official CLI, which scaffolds a complete Express application with Igniter.js:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npx create-igniter-app@latest my-app --template express
    cd my-app
    npm install
    npm run dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm create igniter-app my-app --template express
    cd my-app
    pnpm install
    pnpm dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn create igniter-app my-app --template express
    cd my-app
    yarn install
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx create-igniter-app my-app --template express
    cd my-app
    bun install
    bun dev
    ```
  </Tab>
</Tabs>

Your API runs at `http://localhost:3000/api/v1`, and interactive docs at `http://localhost:3000/api/v1/docs` 🚀

***

## Manual Setup

<Card title="Complete Express Setup Guide">
  <Steps>
    <Step>
      ### Prerequisites

      Before you begin, ensure you have:

      * **Node.js** 18.0+ (20.0+ recommended)
      * **Express** 4.0+
      * **TypeScript** 5.0+
    </Step>

    <Step>
      ### Install Dependencies

      Install Igniter.js, Express, and Zod for schema validation:

      <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
        <Tab value="npm">
          ```bash
          npm install @igniter-js/core express zod
          npm install -D @types/express tsx
          ```
        </Tab>

        <Tab value="pnpm">
          ```bash
          pnpm add @igniter-js/core express zod
          pnpm add -D @types/express tsx
          ```
        </Tab>

        <Tab value="yarn">
          ```bash
          yarn add @igniter-js/core express zod
          yarn add -D @types/express tsx
          ```
        </Tab>

        <Tab value="bun">
          ```bash
          bun add @igniter-js/core express zod
          bun add -D @types/express
          ```
        </Tab>
      </Tabs>

      The `tsx` package enables running TypeScript directly during development without a build step.
    </Step>

    <Step>
      ### Define Application Context

      The context defines dependencies available throughout your API. Create `src/igniter.context.ts`:

      ```typescript title="src/igniter.context.ts"
      /**
       * Application Context Type
       * Defines what dependencies are available to all API handlers
       */
      export interface AppContext {
        // Add your dependencies here, e.g.:
        // db: PrismaClient
        // logger: Logger
      }

      /**
       * Context Factory
       * Creates the context instance passed to handlers
       */
      export function createIgniterAppContext(): AppContext {
        return {
          // Initialize dependencies here
        }
      }
      ```
    </Step>

    <Step>
      ### Initialize Igniter.js

      Create the main Igniter instance. Create `src/igniter.ts`:

      ```typescript title="src/igniter.ts"
      import { Igniter } from '@igniter-js/core'
      import { createIgniterAppContext } from './igniter.context'

      export const igniter = Igniter
        .context(createIgniterAppContext())
        .config({
          baseURL: process.env.IGNITER_API_URL || 'http://localhost:3000',
          basePATH: process.env.IGNITER_API_BASE_PATH || '/api/v1',
        })
        .docs({
          info: {
            title: 'My Express API',
            version: '1.0.0',
            description: 'REST API built with Express and Igniter.js',
          }
        })
        .create()
      ```
    </Step>

    <Step>
      ### Create Your First Controller

      Controllers group related endpoints. Create `src/features/example/controllers/example.controller.ts`:

      ```typescript title="src/features/example/controllers/example.controller.ts"
      import { igniter } from '@/igniter'

      export const exampleController = igniter.controller({
        name: 'Example',
        path: '/example',
        actions: {
          hello: igniter.query({
            path: '/hello',
            handler: async ({ response }) => {
              return response.success({ 
                message: 'Hello from Igniter.js with Express!',
                timestamp: new Date().toISOString()
              })
            },
          }),
        },
      })
      ```

      Create barrel export at `src/features/example/index.ts`:

      ```typescript title="src/features/example/index.ts"
      export * from './controllers/example.controller'
      ```

      This creates `GET /api/v1/example/hello` with fully typed responses.
    </Step>

    <Step>
      ### Create Application Router

      The router assembles all controllers. Create `src/igniter.router.ts`:

      ```typescript title="src/igniter.router.ts"
      import { igniter } from './igniter'
      import { exampleController } from './features/example'

      export const AppRouter = igniter.router({
        controllers: {
          example: exampleController
        }
      })

            export type AppRouterType = typeof AppRouter
      ```
    </Step>

    <Step>
      ### Set Up Express Server

      Connect the router to Express using the adapter. Create `src/index.ts`:

      ```typescript title="src/index.ts"
      import express from 'express'
      import { expressAdapter } from '@igniter-js/core/adapters'
      import { AppRouter } from './igniter.router'

      const app = express()

      const IGNITER_API_BASE_PATH = process.env.IGNITER_API_BASE_PATH || '/api/v1'
      const PORT = process.env.PORT || 3000

      // Mount the Igniter.js router
      app.use(IGNITER_API_BASE_PATH, expressAdapter(AppRouter.handler))

      // Start the server
      app.listen(PORT, () => {
        console.log(`🚀 Server running at http://localhost:${PORT}`)
      })
      ```

      The `expressAdapter` converts Igniter.js's universal handler into Express-compatible middleware.

      ### Step 7: Add Development Scripts

      Update your `package.json`:

      ```json title="package.json"
      {
        "scripts": {
          "dev": "tsx watch src/index.ts",
          "build": "tsc",
          "start": "node dist/index.js"
        }
      }
      ```

      Now run `npm run dev` to start the development server with hot reload!
    </Step>
  </Steps>
</Card>

## Using Express Middleware

Express middleware works seamlessly with Igniter.js. Add middleware before mounting the Igniter router:

```typescript title="src/index.ts"
import express from 'express'
import cors from 'cors'
import helmet from 'helmet'
import compression from 'compression'
import { expressAdapter } from '@igniter-js/core/adapters'
import { AppRouter } from './igniter.router'

const app = express()

// Add Express middleware
app.use(cors())
app.use(helmet())
app.use(compression())
app.use(express.json())
app.use(express.urlencoded({ extended: true }))

// Add custom middleware
app.use((req, res, next) => {
  console.log(`${req.method} ${req.path}`)
  next()
})

// Mount Igniter.js router
app.use('/api/v1', expressAdapter(AppRouter.handler))

app.listen(3000)
```

Middleware like CORS, security headers, compression, and logging work exactly as you'd expect in Express.

***

## Type-Safe Client

Create a type-safe client for consuming your API. Create `src/igniter.client.ts`:

```typescript title="src/igniter.client.ts"
import { createIgniterClient } from '@igniter-js/core/client'
import type { AppRouterType } from './igniter.router'

export const api = createIgniterClient<AppRouterType>({
  baseURL: process.env.IGNITER_API_URL || 'http://localhost:3000',
  basePATH: process.env.IGNITER_API_BASE_PATH || '/api/v1',
  router: () => require('./igniter.router').AppRouter,
})

export type ApiClient = typeof api
```

Use it anywhere in your application:

```typescript
// Fully typed request and response
const { message } = await api.example.hello.query()
```

***

## Igniter Studio (API Playground)

Igniter.js includes an interactive API playground called **Igniter Studio**. It's automatically available at `/api/v1/docs` when you configure the `.docs()` method.

To access it:

1. Start your dev server: `npm run dev`
2. Navigate to `http://localhost:3000/api/v1/docs`
3. You'll see an interactive interface where you can:
   * Browse all API endpoints
   * View request/response schemas
   * Test endpoints directly
   * See auto-generated examples

The playground updates automatically as you add endpoints.

***

## Environment Variables

Create a `.env` file for configuration:

```bash title=".env"
PORT=3000
IGNITER_API_BASE_PATH=/api/v1
IGNITER_API_URL=http://localhost:3000
NODE_ENV=development
```

***

## Project Structure

Here's the recommended structure:

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="features">
      <Folder name="example">
        <Folder name="controllers">
          <File name="example.controller.ts" />
        </Folder>

        <File name="index.ts" />
      </Folder>
    </Folder>

    <Folder name="docs">
      <File name="openapi.json" />
    </Folder>

    <File name="index.ts" />

    <File name="igniter.ts" />

    <File name="igniter.context.ts" />

    <File name="igniter.router.ts" />

    <File name="igniter.client.ts" />

    <File name="igniter.schema.ts" />
  </Folder>

  <File name="package.json" />

  <File name="tsconfig.json" />
</Files>

***

## Next Steps

<Cards>
  <Card title="Core Concepts" href="/docs/builder">
    Learn about Builder, Router, and Controllers
  </Card>

  <Card title="Actions" href="/docs/actions">
    Create queries and mutations with validation
  </Card>

  <Card title="Middleware" href="/docs/middleware">
    Add authentication and custom middleware
  </Card>
</Cards>


---

# Next.js

> Build full-stack, type-safe applications with Igniter.js and Next.js App Router.
URL: https://igniterjs.com/docs/core/nextjs

Igniter.js integrates seamlessly with Next.js to provide end-to-end type safety between your React components and API layer. This guide walks you through building a complete full-stack application with the Next.js App Router.

The combination delivers the best of both worlds: Next.js's excellent developer experience with React Server Components, paired with Igniter.js's automatic type inference and runtime safety. You'll write less boilerplate, catch more bugs at compile time, and ship features faster.

<Callout type="info" title="App Router Required">
  This guide uses Next.js 15+ with the App Router. The Pages Router is not supported.
</Callout>

***

## Quick Start

The fastest way to start is using the official CLI, which scaffolds a complete application with all necessary configuration:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest init
    ```
  </Tab>
</Tabs>

Your app runs at `http://localhost:3000`. API is at `http://localhost:3000/api/v1`, and interactive docs at `http://localhost:3000/api/v1/docs` 🚀

### Direct Command

If you prefer to skip the interactive prompts, you can specify your project name and framework directly:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="direct-command">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest init my-nextjs-app --framework nextjs
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest init my-nextjs-app --framework nextjs
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest init my-nextjs-app --framework nextjs
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest init my-nextjs-app --framework nextjs
    ```
  </Tab>
</Tabs>

This command will create a Next.js project with all Igniter.js features pre-configured.

***

## Manual Setup

<Card title="Complete Next.js Setup Guide">
  <Steps>
    <Step>
      ### Prerequisites

      Before you begin, ensure you have:

      * **Node.js** 22.0+
      * **Next.js** 15.0+ with App Router
      * **TypeScript** 5.0+
    </Step>

    <Step>
      ### Install Core Package

      Install Igniter.js and Zod for schema validation:

      <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
        <Tab value="npm">
          ```bash
          npm install @igniter-js/core zod
          ```
        </Tab>

        <Tab value="pnpm">
          ```bash
          pnpm add @igniter-js/core zod
          ```
        </Tab>

        <Tab value="yarn">
          ```bash
          yarn add @igniter-js/core zod
          ```
        </Tab>

        <Tab value="bun">
          ```bash
          bun add @igniter-js/core zod
          ```
        </Tab>
      </Tabs>

      Zod provides excellent TypeScript inference and runtime validation, making it the recommended choice for Igniter.js projects.
    </Step>

    <Step>
      ### Define Application Context

      The context defines dependencies available throughout your API (database, services, etc.). Create `src/igniter.context.ts`:

      ```typescript title="src/igniter.context.ts"
      /**
       * Application Context Type
       * Defines what dependencies are available to all API handlers
       */
      export interface AppContext {
        // Add your dependencies here, e.g.:
        // db: PrismaClient
        // auth: AuthService
      }

      /**
       * Context Factory
       * Creates the context instance passed to handlers
       */
      export function createIgniterAppContext(): AppContext {
        return {
          // Initialize dependencies here
        }
      }
      ```
    </Step>

    <Step>
      ### Initialize Igniter.js

      Create the main Igniter instance with configuration. Create `src/igniter.ts`:

      ```typescript title="src/igniter.ts"
      import { Igniter } from '@igniter-js/core'
      import { createIgniterAppContext } from './igniter.context'

      export const igniter = Igniter
        .context(createIgniterAppContext())
        .config({
          baseURL: process.env.NEXT_PUBLIC_IGNITER_API_URL || 'http://localhost:3000',
          basePATH: process.env.NEXT_PUBLIC_IGNITER_API_BASE_PATH || '/api/v1',
        })
        .docs({
          info: {
            title: 'My Next.js API',
            version: '1.0.0',
            description: 'API built with Igniter.js',
          }
        })
        .create()
      ```

      The builder pattern makes it easy to add features later like `.store()` (Redis), `.jobs()` (background tasks), `.logger()`, and `.telemetry()`.
    </Step>

    <Step>
      ### Create Your First Controller

      Controllers group related endpoints. Create `src/features/example/controllers/example.controller.ts`:

      ```typescript title="src/features/example/controllers/example.controller.ts"
      import { igniter } from '@/igniter'

      export const exampleController = igniter.controller({
        name: 'Example',
        path: '/example',
        actions: {
          hello: igniter.query({
            path: '/hello',
            handler: async ({ response }) => {
              return response.success({ 
                message: 'Hello from Igniter.js!',
                timestamp: new Date().toISOString()
              })
            },
          }),
        },
      })
      ```

      Create barrel export at `src/features/example/index.ts`:

      ```typescript title="src/features/example/index.ts"
            export * from './controllers/example.controller'
      ```

      This creates `GET /api/v1/example/hello` with fully typed responses.
    </Step>

    <Step>
      ### Create Application Router

      The router assembles all controllers. Create `src/igniter.router.ts`:

      ```typescript title="src/igniter.router.ts"
      import { igniter } from './igniter'
      import { exampleController } from './features/example'

      export const AppRouter = igniter.router({
        controllers: {
          example: exampleController
        }
      })

            export type AppRouterType = typeof AppRouter
      ```

      The type export enables the type-safe client without exposing server implementation.
    </Step>

    <Step>
      ### Create Next.js API Route

      Connect the router to Next.js using the adapter. Create `src/app/api/v1/[[...all]]/route.ts`:

      ```typescript title="src/app/api/v1/[[...all]]/route.ts"
      import { AppRouter } from '@/igniter.router'
      import { nextRouteHandlerAdapter } from '@igniter-js/core/adapters'

      export const { GET, POST, PUT, DELETE } = nextRouteHandlerAdapter(AppRouter)
      ```

      The `[[...all]]` catch-all route handles all methods and paths under `/api/v1/`.

      ### Step 7: Generate Type-Safe Client

      Create the client for frontend usage at `src/igniter.client.ts`:

      ```typescript title="src/igniter.client.ts"
      import { createIgniterClient } from '@igniter-js/core/client'
      import type { AppRouterType } from './igniter.router'

      export const api = createIgniterClient<AppRouterType>({
        baseURL: process.env.NEXT_PUBLIC_IGNITER_API_URL || 'http://localhost:3000',
        basePATH: process.env.NEXT_PUBLIC_IGNITER_API_BASE_PATH || '/api/v1',
        router: () => {
          if (typeof window === 'undefined') {
            return require('./igniter.router').AppRouter
          }
          return require('./igniter.schema').AppRouterSchema
        },
      })

      export type ApiClient = typeof api
      ```

      This client works in both Server and Client Components with full type safety.
    </Step>
  </Steps>
</Card>

## Usage in Components

### Server Components

Use direct API calls in Server Components:

```typescript title="app/page.tsx"
import { api } from '@/igniter.client'

export default async function HomePage() {
  const { message } = await api.example.hello.query()
  
  return <div>Message: {message}</div>
}
```

### Client Components

Use React hooks for automatic loading/error states:

```typescript title="components/example.tsx"
'use client'

import { api } from '@/igniter.client'

export function ExampleComponent() {
  const { data, isLoading, error } = api.example.hello.useQuery()
  
  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>
  
  return <div>Message: {data.message}</div>
}
```

***

## Generating Schema and Docs

Igniter.js can automatically generate OpenAPI schemas and TypeScript types for your API.

### When to Generate Schema

<Callout type="error">
  **Critical:** You MUST run schema generation BEFORE using the client in your frontend. The client depends on the generated schema to function correctly.
</Callout>

<Callout type="info">
  Run this command whenever you modify your API structure (add/remove/modify controllers or actions) OR before using the client for the first time.
</Callout>

### Generate Schema

Run this command whenever you make changes to your API structure:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="generate-schema">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest generate schema
    ```
  </Tab>
</Tabs>

This creates:

* `src/igniter.schema.ts` - Type-safe schema for client-side usage
* `src/docs/openapi.json` - OpenAPI 3.0 specification

### Generate OpenAPI Documentation

To generate or update the OpenAPI specification and interactive documentation:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="generate-docs">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest generate docs
    ```
  </Tab>
</Tabs>

### Update Igniter Config

Import the generated OpenAPI schema in `src/igniter.ts`:

```typescript title="src/igniter.ts"
import { Igniter } from '@igniter-js/core'
import { createIgniterAppContext } from './igniter.context'
import openapi from './docs/openapi.json'

export const igniter = Igniter
  .context(createIgniterAppContext())
  .config({
    baseURL: process.env.NEXT_PUBLIC_IGNITER_API_URL || 'http://localhost:3000',
    basePATH: process.env.NEXT_PUBLIC_IGNITER_API_BASE_PATH || '/api/v1',
  })
  .docs({
    openapi, // ← Add generated OpenAPI
    info: {
      title: 'My Next.js API',
      version: '1.0.0',
      description: 'API built with Igniter.js',
    }
  })
  .create()
```

***

## Igniter Studio (API Playground)

Igniter.js includes an interactive API playground called **Igniter Studio**, powered by Scalar. It's automatically available at `/api/v1/docs` when you configure the `.docs()` method.

To access it:

1. Start your dev server: `npm run dev`
2. Navigate to `http://localhost:3000/api/v1/docs`
3. You'll see an interactive interface where you can:
   * Browse all API endpoints
   * View request/response schemas
   * Test endpoints directly in the browser
   * See auto-generated examples

The playground updates automatically as you add new endpoints or modify existing ones. It's perfect for API development and testing without needing external tools like Postman.

***

## Project Structure

Here's the recommended structure:

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="app">
      <Folder name="api">
        <Folder name="v1">
          <Folder name="[[...all]]">
            <File name="route.ts" />
          </Folder>
        </Folder>
      </Folder>
    </Folder>

    <Folder name="features">
      <Folder name="example">
        <Folder name="controllers">
          <File name="example.controller.ts" />
        </Folder>

        <File name="index.ts" />
      </Folder>
    </Folder>

    <Folder name="docs">
      <File name="openapi.json" />
    </Folder>

    <File name="igniter.ts" />

    <File name="igniter.context.ts" />

    <File name="igniter.router.ts" />

    <File name="igniter.client.ts" />

    <File name="igniter.schema.ts" />
  </Folder>
</Files>

***

## Next Steps

<Cards>
  <Card title="Core Concepts" href="/docs/builder">
    Learn about Builder, Router, and Controllers
  </Card>

  <Card title="Actions" href="/docs/actions">
    Create queries and mutations with validation
  </Card>

  <Card title="Client" href="/docs/client">
    Master the type-safe client and hooks
  </Card>
</Cards>


---

# Installation

> Get started with Igniter.js by choosing your preferred framework and following the installation guide.
URL: https://igniterjs.com/docs/core/page

Choose your framework to get started with Igniter.js. Each guide provides step-by-step instructions tailored to your development environment.

## Framework Guides

Select your framework below for detailed installation and setup instructions:

<Cards>
  <Card title="Next.js" description="Full-stack React framework with SSR and API routes" href="/docs/nextjs" icon={<NextJsIcon className="size-6" />} />

  <Card title="Vite" description="Lightning-fast build tool for modern web projects" href="/docs/vite" icon={<ViteIcon className="size-6" />} />

  <Card title="Express" description="Fast, unopinionated web framework for Node.js" href="/docs/express" icon={<ExpressIcon className="size-6" />} />

  <Card title="Bun" description="Fast all-in-one JavaScript runtime and toolkit" href="/docs/bun" icon={<BunIcon className="size-6" />} />

  <Card title="Deno" description="Secure runtime for JavaScript and TypeScript" href="/docs/deno" icon={<DenoIcon className="size-6" />} />
</Cards>

***

## Quick Start

If you're not sure which framework to choose, or want to quickly test Igniter.js features:

<Steps>
  <Step>
    ### Use the CLI

    Start a new project with our interactive CLI:

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        npx @igniter-js/cli@latest init
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @igniter-js/cli@latest init
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @igniter-js/cli@latest init
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @igniter-js/cli@latest init
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Choose your template

    The CLI will guide you through:

    * Framework selection (Next.js, Vite, Express, etc.)
    * TypeScript configuration
    * Database setup (optional)
    * Additional features (auth, jobs, etc.)
  </Step>

  <Step>
    ### Start developing

    ```bash
    cd my-igniter-app
    npm run dev
    ```
  </Step>
</Steps>

***

## Requirements

Before installing Igniter.js, ensure you have:

* **Node.js** 22.0 or higher
* **Package Manager**: npm, pnpm, yarn, or bun
* **TypeScript** 5.0 or higher (configured in your project)

<Callout type="info" title="TypeScript Required">
  Igniter.js is built with TypeScript-first principles and requires TypeScript for full type safety and autocomplete features.
</Callout>

***

## What's Next?

After installation, explore the core concepts:

* [**Builder**](/docs/builder) - Learn how to create your Igniter.js instance
* [**Router**](/docs/router) - Understand routing and controllers
* [**Actions**](/docs/actions) - Create queries and mutations
* [**Client**](/docs/client) - Use the auto-generated type-safe client

<Callout type="success" title="Need Help?">
  Join our [Discord community](https://discord.gg/igniterjs) or check out [GitHub Discussions](https://github.com/igniterjs/igniter/discussions) for support.
</Callout>


---

# Vite

> Build modern full-stack applications with Igniter.js and Vite, the lightning-fast build tool for modern web development.
URL: https://igniterjs.com/docs/core/vite

Vite is a next-generation frontend build tool that provides an instant dev server and lightning-fast hot module replacement. When combined with Igniter.js, you can build full-stack applications with a type-safe API backend and a modern React/Vue/Svelte frontend—all in a single codebase with excellent developer experience.

This guide focuses on integrating Igniter.js as an API backend within a Vite project. You'll learn how to set up API routes that work seamlessly with Vite's dev server and production builds, while maintaining full type safety between your frontend and backend.

<Callout type="info" title="Full-Stack Development">
  Vite + Igniter.js enables full-stack development with frontend frameworks like React, Vue, or Svelte while maintaining a type-safe API layer.
</Callout>

***

## Quick Start

For a complete full-stack setup, we recommend using **TanStack Start** (Vite-powered React framework):

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest init
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest init
    ```
  </Tab>
</Tabs>

Your app runs at `http://localhost:3000`, API at `http://localhost:3000/api/v1`, and docs at `http://localhost:3000/api/v1/docs` 🚀

### Direct Command

If you prefer to skip the interactive prompts, you can specify your project name and framework directly:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="direct-command">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest init my-vite-app --framework tanstack-start
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest init my-vite-app --framework tanstack-start
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest init my-vite-app --framework tanstack-start
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest init my-vite-app --framework tanstack-start
    ```
  </Tab>
</Tabs>

This command will create a TanStack Start project with all Igniter.js features pre-configured.

***

## Manual Setup with Vite

<Card title="Complete Vite Setup Guide">
  <Steps>
    <Step>
      ### Prerequisites

      Before you begin, ensure you have:

      * **Node.js** 22.0+
      * **Vite** 5.0+
      * A Vite project (React, Vue, Svelte, etc.)
    </Step>

    <Step>
      ### Install Dependencies

      Add Igniter.js to your Vite project:

      <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
        <Tab value="npm">
          ```bash
          npm install @igniter-js/core zod
          ```
        </Tab>

        <Tab value="pnpm">
          ```bash
          pnpm add @igniter-js/core zod
          ```
        </Tab>

        <Tab value="yarn">
          ```bash
          yarn add @igniter-js/core zod
          ```
        </Tab>

        <Tab value="bun">
          ```bash
          bun add @igniter-js/core zod
          ```
        </Tab>
      </Tabs>
    </Step>

    <Step>
      ### Configure Vite for API Routes

      Update your `vite.config.ts` to proxy API requests during development:

      ```typescript title="vite.config.ts"
      import { defineConfig } from 'vite'
      import react from '@vitejs/plugin-react'

      export default defineConfig({
        plugins: [react()],
        
        server: {
          proxy: {
            // Proxy API requests to your backend
            '/api': {
              target: 'http://localhost:3001',
              changeOrigin: true,
            },
          },
        },
      })
      ```

      This configuration proxies `/api/*` requests to your Igniter.js server during development.
    </Step>

    <Step>
      ### Define Application Context

      Create the context for your API. Create `src/igniter.context.ts`:

      ```typescript title="src/igniter.context.ts"
      /**
       * Application Context Type
       * Defines what dependencies are available to all API handlers
       */
      export interface AppContext {
        // Add your dependencies here, e.g.:
        // db: PrismaClient
        // auth: AuthService
      }

      /**
       * Context Factory
       * Creates the context instance passed to handlers
       */
      export function createIgniterAppContext(): AppContext {
        return {
          // Initialize dependencies here
        }
      }
      ```
    </Step>

    <Step>
      ### Initialize Igniter.js

      Create the main Igniter instance. Create `src/igniter.ts`:

      ```typescript title="src/igniter.ts"
      import { Igniter } from '@igniter-js/core'
      import { createIgniterAppContext } from './igniter.context'

      export const igniter = Igniter
        .context(createIgniterAppContext())
        .config({
          baseURL: import.meta.env.VITE_API_URL || 'http://localhost:3001',
          basePATH: import.meta.env.VITE_API_BASE_PATH || '/api/v1',
        })
        .docs({
          info: {
            title: 'My Vite App API',
            version: '1.0.0',
            description: 'Full-stack app with Vite and Igniter.js',
          }
        })
        .create()
      ```

      Note: Vite uses `import.meta.env` for environment variables, not `process.env`.
    </Step>

    <Step>
      ### Create Your First Controller

      Controllers group related endpoints. Create `src/features/example/controllers/example.controller.ts`:

      ```typescript title="src/features/example/controllers/example.controller.ts"
      import { igniter } from '@/igniter'

      export const exampleController = igniter.controller({
        name: 'Example',
        path: '/example',
        actions: {
          hello: igniter.query({
            path: '/hello',
            handler: async ({ response }) => {
              return response.success({ 
                message: 'Hello from Igniter.js with Vite!',
                timestamp: new Date().toISOString()
              })
            },
          }),
        },
      })
      ```

      Create barrel export at `src/features/example/index.ts`:

      ```typescript title="src/features/example/index.ts"
            export * from './controllers/example.controller'
      ```
    </Step>

    <Step>
      ### Create Application Router

      The router assembles all controllers. Create `src/igniter.router.ts`:

      ```typescript title="src/igniter.router.ts"
      import { igniter } from './igniter'
      import { exampleController } from './features/example'

      export const AppRouter = igniter.router({
        controllers: {
          example: exampleController
        }
      })

            export type AppRouterType = typeof AppRouter
      ```
    </Step>

    <Step>
      ### Create Separate API Server

      For Vite projects, run the API as a separate Node.js server. Create `server/index.ts`:

      ```typescript title="server/index.ts"
      import express from 'express'
      import { expressAdapter } from '@igniter-js/core/adapters'
      import { AppRouter } from '../src/igniter.router'

      const app = express()

      const PORT = process.env.API_PORT || 3001
      const API_BASE_PATH = '/api/v1'

      // Mount Igniter.js router
      app.use(API_BASE_PATH, expressAdapter(AppRouter.handler))

      app.listen(PORT, () => {
        console.log(`🚀 API Server running at http://localhost:${PORT}`)
      })
      ```

      Add to `package.json`:

      ```json title="package.json"
      {
        "scripts": {
          "dev": "concurrently \"vite\" \"tsx watch server/index.ts\"",
          "dev:api": "tsx watch server/index.ts",
          "dev:frontend": "vite"
        }
      }
      ```

      Install `concurrently`:

      ```bash
            npm install -D concurrently tsx
      ```
    </Step>
  </Steps>
</Card>

## Using in React Components

### Type-Safe Client

Create a type-safe client. Create `src/igniter.client.ts`:

```typescript title="src/igniter.client.ts"
import { createIgniterClient } from '@igniter-js/core/client'
import type { AppRouterType } from './igniter.router'

export const api = createIgniterClient<AppRouterType>({
  baseURL: import.meta.env.VITE_API_URL || 'http://localhost:3001',
  basePATH: import.meta.env.VITE_API_BASE_PATH || '/api/v1',
  router: () => import('./igniter.schema').then(m => m.AppRouterSchema),
})

export type ApiClient = typeof api
```

### Using Client Components

Use React hooks for automatic loading/error states:

```tsx title="src/components/Example.tsx"
'use client'

import { api } from '@/igniter.client'

export function Example() {
  const { data, isLoading, error } = api.example.hello.useQuery()

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return <div>Message: {data.message}</div>
}
```

***

## Generating Schema and Docs

Since TanStack Start is a full-stack framework, you'll need to generate the client schema whenever you modify your API.

### When to Generate Schema

<Callout type="error">
  **Critical:** You MUST run schema generation BEFORE using the client in your frontend. The client depends on the generated schema to function correctly.
</Callout>

<Callout type="info">
  Run this command whenever you modify your API structure (add/remove/modify controllers or actions) OR before using the client for the first time.
</Callout>

### Generate Schema

Run this command whenever you make changes to your API structure:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="generate-schema">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest generate schema
    ```
  </Tab>
</Tabs>

This creates:

* `src/igniter.schema.ts` - Type-safe schema for client-side usage
* `src/docs/openapi.json` - OpenAPI 3.0 specification

### Generate OpenAPI Documentation

To generate or update the OpenAPI specification and interactive documentation:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="generate-docs">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest generate docs
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest generate docs
    ```
  </Tab>
</Tabs>

***

## Environment Variables

Create `.env` for Vite environment variables:

```bash title=".env"
VITE_API_URL=http://localhost:3001
VITE_API_BASE_PATH=/api/v1
```

Access in code using `import.meta.env.VITE_*`:

```typescript
const apiUrl = import.meta.env.VITE_API_URL
```

***

## Production Build

### Build Both Frontend and API

Update `package.json`:

```json
{
  "scripts": {
    "build": "tsc && vite build",
    "build:api": "tsc --project tsconfig.server.json",
    "preview": "vite preview"
  }
}
```

Create `tsconfig.server.json` for the API:

```json title="tsconfig.server.json"
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist/server",
    "module": "commonjs",
    "target": "ES2020"
  },
  "include": ["server/**/*", "src/igniter*.ts", "src/features/**/*"]
}
```

***

## Alternative: TanStack Start

For the best full-stack Vite experience, use **TanStack Start** which includes:

* Built-in API routes (no separate server needed)
* File-based routing
* SSR and streaming
* Type-safe data loading

See the [TanStack Start guide](/docs/installation/tanstack-start) for details.

***

## Project Structure

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="features">
      <Folder name="example">
        <Folder name="controllers">
          <File name="example.controller.ts" />
        </Folder>

        <File name="index.ts" />
      </Folder>
    </Folder>

    <Folder name="components">
      <File name="Example.tsx" />
    </Folder>

    <File name="igniter.ts" />

    <File name="igniter.context.ts" />

    <File name="igniter.router.ts" />

    <File name="igniter.client.ts" />

    <File name="main.tsx" />
  </Folder>

  <Folder name="server">
    <File name="index.ts" />
  </Folder>

  <File name="vite.config.ts" />

  <File name="package.json" />
</Files>

***

## Next Steps

<Cards>
  <Card title="TanStack Start" href="/docs/installation/tanstack-start">
    Full-stack framework with built-in API routes
  </Card>

  <Card title="Client" href="/docs/client">
    Type-safe client with React hooks
  </Card>

  <Card title="Actions" href="/docs/actions">
    Create queries and mutations
  </Card>
</Cards>


---

# Client

> Learn how to consume your Igniter.js API from the client-side using type-safe hooks, queries, mutations, and real-time subscriptions in React applications.
URL: https://igniterjs.com/docs/core/client

## Overview

The **Igniter.js Client** provides a fully type-safe way to consume your API from React applications. It automatically generates typed hooks (`useQuery`, `useMutation`, `useRealtime`) based on your router definition, giving you end-to-end type safety from server to client.

```typescript
// server/igniter.ts
export const igniter = createIgniterBuilder()
  .context<{ db: Database }>()
  .create();

export const router = igniter.router({
  users: userController
});

export type AppRouter = typeof router;
```

```tsx
// client/app.tsx
import { createIgniterClient } from '@igniter-js/core/client';
import type { AppRouter } from '../server/igniter';

const client = createIgniterClient<AppRouter>({
  baseURL: 'http://localhost:3000',
  basePATH: '/api/v1',
  router: () => router  // ✅ Type-safe client!
});

function UserList() {
  const { data, isLoading } = client.users.list.useQuery();
  //     ^? { users: User[] } - Fully typed!
  
  if (isLoading) return <div>Loading...</div>;
  
  return (
    <ul>
      {data.users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}
```

<Callout type="success" title="Zero Configuration">
  No code generation, no manual types. The client automatically infers all types from your router!
</Callout>

***

## Client Setup

### Install Dependencies

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/core react
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/core react
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/core react
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/core react
    ```
  </Tab>
</Tabs>

### Create the Client

```typescript
// lib/client.ts
import { createIgniterClient } from '@igniter-js/core/client';
import type { AppRouter } from '../server/igniter';

export const client = createIgniterClient<AppRouter>({
  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000',
  basePATH: '/api/v1',
  router: () => import('../server/igniter').then(m => m.router)
});
```

### Wrap Your App with Provider

```tsx
// app/layout.tsx
import { IgniterProvider } from '@igniter-js/core/client';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <IgniterProvider>
          {children}
        </IgniterProvider>
      </body>
    </html>
  );
}
```

***

## useQuery Hook

Use `useQuery` for **fetching data** (GET requests):

### Basic Query

```tsx
function UserProfile({ userId }: { userId: string }) {
  const { data, isLoading, error } = client.users.getById.useQuery({
    params: { id: userId }
  });
  
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <div>
      <h1>{data.user.name}</h1>
      <p>{data.user.email}</p>
    </div>
  );
}
```

### Query with Parameters

```tsx
function ProductSearch() {
  const [searchTerm, setSearchTerm] = useState('');
  
  const { data, isLoading } = client.products.search.useQuery({
    query: {
      q: searchTerm,
      limit: 20
    }
  });
  
  return (
    <div>
      <input 
        value={searchTerm} 
        onChange={(e) => setSearchTerm(e.target.value)}
        placeholder="Search products..."
      />
      
      {isLoading ? (
        <div>Searching...</div>
      ) : (
        <ul>
          {data.products.map(product => (
            <li key={product.id}>{product.name}</li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

### useQuery Options

```typescript
const { data, isLoading, error, refetch, invalidate } = client.users.list.useQuery({
  // Query parameters
  query: { status: 'active' },
  params: { id: '123' },
  
  // Initial data (SSR)
  initialData: { users: [] },
  
  // Caching
  staleTime: 5000,  // Consider data fresh for 5 seconds
  
  // Auto-refetch behaviors
  enabled: true,                           // Enable/disable query
  refetchOnMount: true,                    // Refetch on component mount
  refetchOnWindowFocus: true,              // Refetch when window regains focus
  refetchOnReconnect: true,                // Refetch when internet reconnects
  refetchInterval: 10000,                  // Poll every 10 seconds
  refetchIntervalInBackground: false,      // Don't poll when tab is hidden
  
  // Lifecycle callbacks
  onLoading: (isLoading) => console.log('Loading:', isLoading),
  onSuccess: (data) => console.log('Success:', data),
  onError: (error) => console.error('Error:', error),
  onRequest: (response) => console.log('Request complete:', response),
  onSettled: (data, error) => console.log('Settled:', { data, error })
});
```

### useQuery Return Values

```typescript
{
  // Data
  data: TData | null,              // Response data
  error: TError | null,            // Error object
  variables: TInput | undefined,   // Last used query parameters
  
  // Status booleans
  isLoading: boolean,              // Initial load
  isFetching: boolean,             // Any fetch (including refetch)
  isSuccess: boolean,              // Successful response
  isError: boolean,                // Error occurred
  status: 'loading' | 'success' | 'error',
  
  // Actions
  refetch: (invalidateCache?: boolean) => void,  // Refetch with same params
  execute: (params?: TInput) => Promise<TData>,  // Fetch with new params
  invalidate: () => void                         // Invalidate cache
}
```

***

## useMutation Hook

Use `useMutation` for **modifying data** (POST, PUT, PATCH, DELETE):

### Basic Mutation

```tsx
function CreateUserForm() {
  const { mutate, isLoading, error } = client.users.create.useMutation();
  
  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    
    await mutate({
      body: {
        name: formData.get('name') as string,
        email: formData.get('email') as string
      }
    });
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <input name="name" required />
      <input name="email" type="email" required />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Creating...' : 'Create User'}
      </button>
      {error && <p>Error: {error.message}</p>}
    </form>
  );
}
```

### Mutation with Callbacks

```tsx
function DeletePostButton({ postId }: { postId: string }) {
  const { mutate, isLoading } = client.posts.delete.useMutation({
    onSuccess: (data) => {
      console.log('Post deleted:', data);
      // Invalidate queries
      queryClient.invalidate(['posts']);
    },
    onError: (error) => {
      console.error('Failed to delete:', error);
      alert('Failed to delete post');
    }
  });
  
  return (
    <button 
      onClick={() => mutate({ params: { id: postId } })}
      disabled={isLoading}
    >
      {isLoading ? 'Deleting...' : 'Delete'}
    </button>
  );
}
```

### useMutation Options

```typescript
const { mutate, data, error, isLoading, retry } = client.users.update.useMutation({
  // Static parameters (applied to all mutations)
  params: { id: userId },
  
  // Lifecycle callbacks
  onLoading: (isLoading) => console.log('Loading:', isLoading),
  onSuccess: (data) => console.log('Success:', data),
  onError: (error) => console.error('Error:', error),
  onRequest: (response) => console.log('Request complete:', response),
  onSettled: (data, error) => console.log('Settled:', { data, error })
});

// Call mutation
mutate({
  body: { name: 'New Name' },
  // These override static params
  params: { id: '456' }
});
```

### useMutation Return Values

```typescript
{
  // Data
  data: TData | null,              // Response data
  error: TError | null,            // Error object
  variables: TInput | undefined,   // Last used mutation parameters
  
  // Status booleans
  isLoading: boolean,
  isSuccess: boolean,
  isError: boolean,
  status: 'idle' | 'loading' | 'success' | 'error',
  
  // Actions
  mutate: (params: TInput) => Promise<TData>,  // Execute mutation
  retry: () => void                             // Retry last mutation
}
```

***

## Real-Time with useRealtime

Subscribe to Server-Sent Events (SSE) streams:

### Basic Real-Time Subscription

```tsx
function LiveNotifications({ userId }: { userId: string }) {
  const { data, isConnected } = client.notifications.live.useRealtime({
    channelId: `notifications:user:${userId}`,
    
    onMessage: (notification) => {
      console.log('New notification:', notification);
      // Show toast, play sound, etc.
    },
    
    onConnect: () => {
      console.log('Connected to notifications stream');
    },
    
    onDisconnect: () => {
      console.log('Disconnected from notifications stream');
    }
  });
  
  return (
    <div>
      <div>Status: {isConnected ? '🟢 Connected' : '🔴 Disconnected'}</div>
      
      {data && (
        <div className="notification">
          <strong>{data.title}</strong>
          <p>{data.message}</p>
        </div>
      )}
    </div>
  );
}
```

### Real-Time with Initial Data

```tsx
function LiveMetrics() {
  const { data, isConnected } = client.metrics.stream.useRealtime({
    channelId: 'metrics:dashboard',
    
    initialData: {
      cpu: 0,
      memory: 0,
      requests: 0
    },
    
    onMessage: (metrics) => {
      // Update chart, gauge, etc.
    }
  });
  
  return (
    <div>
      <h2>Live Server Metrics</h2>
      <div>CPU: {data?.cpu}%</div>
      <div>Memory: {data?.memory}%</div>
      <div>Requests/s: {data?.requests}</div>
    </div>
  );
}
```

***

## Direct Fetching (No Hooks)

Use `.query()` or `.mutate()` for non-hook scenarios:

### Direct Query

```typescript
// Outside React component
async function fetchUser(id: string) {
  const response = await client.users.getById.query({
    params: { id }
  });
  
  if (response.error) {
    throw new Error(response.error.message);
  }
  
  return response.data;
}
```

### Direct Mutation

```typescript
// In event handler, middleware, etc.
async function createUser(userData: CreateUserInput) {
  const response = await client.users.create.mutate({
    body: userData
  });
  
  return response.data;
}
```

***

## Cache Management

### Using IgniterQueryClient

```tsx
import { useIgniterQueryClient } from '@igniter-js/core/client';

function Dashboard() {
  const queryClient = useIgniterQueryClient();
  
  const handleRefresh = () => {
    // Invalidate all 'users' queries
    queryClient.invalidate(['users.*']);
    
    // Invalidate specific query
    queryClient.invalidate(['users.list']);
    
    // Invalidate multiple
    queryClient.invalidate(['users.list', 'posts.list']);
  };
  
  return <button onClick={handleRefresh}>Refresh Data</button>;
}
```

### Automatic Cache Invalidation

When using `response.revalidate()` on the server, connected clients are automatically notified:

```typescript
// Server-side
const createPost = igniter.mutation({
  name: 'Create Post',
  description: 'Create a new post',
  path: '/',
  method: 'POST',
  handler: async ({ response }) => {
    const post = await db.posts.create({ data: {...} });
    
    // ✅ Automatically invalidates 'posts' query on all clients
    return response
      .revalidate(['posts', 'dashboard'])
      .created({ post });
  }
});
```

***

## Error Handling

### Handle Errors in useQuery

```tsx
function UserProfile({ userId }: { userId: string }) {
  const { data, error, isError, isLoading } = client.users.getById.useQuery({
    params: { id: userId },
    
    onError: (error) => {
      // Log to error tracking service
      console.error('Failed to load user:', error);
    }
  });
  
  if (isLoading) return <Skeleton />;
  
  if (isError) {
    return (
      <div className="error">
        <h2>Failed to load user</h2>
        <p>{error.message}</p>
        {error.code === 'ERR_NOT_FOUND' && (
          <p>User not found</p>
        )}
      </div>
    );
  }
  
  return <div>{data.user.name}</div>;
}
```

### Handle Errors in useMutation

```tsx
function CreatePostForm() {
  const { mutate, error, isError } = client.posts.create.useMutation({
    onError: (error) => {
      if (error.code === 'VALIDATION_ERROR') {
        // Show validation errors
        console.log(error.details);
      } else {
        // Generic error
        alert('Failed to create post');
      }
    }
  });
  
  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      mutate({ body: { title: '...', content: '...' } });
    }}>
      {/* Form fields */}
      {isError && (
        <div className="error">{error.message}</div>
      )}
      <button type="submit">Create</button>
    </form>
  );
}
```

***

## Server-Side Rendering (SSR)

### Next.js App Router

```tsx
// app/users/page.tsx
import { client } from '@/lib/client';

export default async function UsersPage() {
  // ✅ Fetch on server
  const { data } = await client.users.list.query();
  
  return (
    <div>
      <h1>Users</h1>
      <UserList initialData={data} />
    </div>
  );
}

// components/UserList.tsx
'use client';

function UserList({ initialData }) {
  const { data } = client.users.list.useQuery({
    initialData  // ✅ Hydrate with server data
  });
  
  return (
    <ul>
      {data.users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}
```

### Next.js Pages Router

```tsx
// pages/users.tsx
export async function getServerSideProps() {
  const { data } = await client.users.list.query();
  
  return {
    props: { users: data.users }
  };
}

export default function UsersPage({ users }) {
  const { data } = client.users.list.useQuery({
    initialData: { users }
  });
  
  return <ul>{/* ... */}</ul>;
}
```

***

## Best Practices

### 1. Create a Shared Client Instance

```typescript
// ✅ Good - Single instance
// lib/client.ts
export const client = createIgniterClient<AppRouter>({ ... });

// ❌ Bad - Multiple instances
function Component() {
  const client = createIgniterClient<AppRouter>({ ... });
}
```

### 2. Use initialData for SSR

```tsx
// ✅ Good - Hydrate with server data
const { data } = client.users.list.useQuery({
  initialData: serverData
});

// ❌ Bad - Redundant fetch on client
const { data } = client.users.list.useQuery();
```

### 3. Invalidate After Mutations

```tsx
// ✅ Good - Auto-refresh related queries
const { mutate } = client.users.create.useMutation({
  onSuccess: () => {
    queryClient.invalidate(['users.list']);
  }
});

// ❌ Bad - Stale data
const { mutate } = client.users.create.useMutation();
```

### 4. Handle Loading and Error States

```tsx
// ✅ Good - Complete UX
if (isLoading) return <Skeleton />;
if (isError) return <ErrorMessage error={error} />;
return <Content data={data} />;

// ❌ Bad - No feedback
return <Content data={data} />;
```

***

## Client Maintenance

### Schema Synchronization

<Callout type="error">
  **Critical:** You MUST run schema generation BEFORE using the client. The client depends entirely on the generated schema to function.
</Callout>

<Callout type="info">
  The client types are automatically derived from your server-side controllers and actions. Without the generated schema, the client will not work.
</Callout>

When your API changes (new controllers, actions, or modified signatures), update the client:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="client-maintenance">
  <Tab value="npm">
    ```bash
    npx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @igniter-js/cli@latest generate schema
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @igniter-js/cli@latest generate schema
    ```
  </Tab>
</Tabs>

This regenerates:

* `src/igniter.schema.ts` - Updated type definitions for full IntelliSense
* Client method signatures that stay in sync with your API

***

## Next Steps

<Cards>
  <Card title="Actions" href="/docs/actions">
    Define queries and mutations
  </Card>

  <Card title="Response Types" href="/docs/response-types">
    Return proper responses
  </Card>

  <Card title="Real-Time" href="/docs/real-time">
    Build real-time features
  </Card>

  <Card title="Testing" href="/docs/testing">
    Test your client code
  </Card>
</Cards>


---

# Google Cloud Storage Adapter

> Connect Igniter Storage to Google Cloud Storage buckets with public delivery.
URL: https://igniterjs.com/docs/storage/google-cloud

## Credentials and Environment

Use a service account JSON (file path or base64) plus bucket details. Set env vars or pass credentials directly.

<TypeTable
  type={{
  IGNITER_STORAGE_GOOGLE_BUCKET: {
    type: "string",
    description: "Bucket name",
    required: true,
  },
  IGNITER_STORAGE_GOOGLE_REGION: {
    type: "string",
    description: "Bucket region",
    required: false,
  },
  IGNITER_STORAGE_GOOGLE_ENDPOINT: {
    type: "string",
    description: "Custom endpoint or emulator",
    required: false,
  },
  IGNITER_STORAGE_GOOGLE_CREDENTIALS_JSON: {
    type: "string",
    description: "Raw JSON credentials",
    required: false,
  },
  IGNITER_STORAGE_GOOGLE_CREDENTIALS_JSON_BASE64: {
    type: "string",
    description: "Base64-encoded credentials JSON",
    required: false,
  },
}}
/>

## Minimal Setup

```typescript
import { IgniterStorage } from "@igniter-js/storage";

export const storage = IgniterStorage.create()
  .withAdapter("google", {
    bucket: process.env.IGNITER_STORAGE_GOOGLE_BUCKET!,
    region: process.env.IGNITER_STORAGE_GOOGLE_REGION,
    endpoint: process.env.IGNITER_STORAGE_GOOGLE_ENDPOINT,
    credentialsJson: process.env.IGNITER_STORAGE_GOOGLE_CREDENTIALS_JSON,
    credentialsJsonBase64:
      process.env.IGNITER_STORAGE_GOOGLE_CREDENTIALS_JSON_BASE64,
  })
  .withUrl(process.env.IGNITER_STORAGE_URL || "https://cdn.example.com")
  .build();
```

<Callout type="warn" title="Public access">
  Ensure the bucket policy/IAM allows public reads if you rely on CDN-style
  URLs. Otherwise, pair this adapter with signed URLs at your CDN or edge layer.
</Callout>

## Emulator and Multi-env

Point `IGNITER_STORAGE_GOOGLE_ENDPOINT` to a local emulator for tests. Use `.withPath('/staging')` to isolate environments in the same bucket while keeping URLs stable (`https://cdn.example.com/staging/...`).

Next: harden uploads with [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation) or explore lifecycle flows in [Architecture](/docs/storage/\(concepts\)/architecture).


---

# Overview

> Understand how @igniter-js/storage organizes uploads with adapters, scopes, and policies to ship reliable file handling fast.
URL: https://igniterjs.com/docs/storage

## Why Storage

Igniter Storage gives you a typed, adapter-based layer for file handling so you can standardize uploads, public URLs, and lifecycle hooks without hand-rolling S3 or GCS code. It keeps infrastructure concerns inside adapters while the manager enforces scopes, policies, and error handling, matching the way core Igniter services stay framework-agnostic. Use it when you need predictable public links, replace strategies, and observability baked into every file operation.

<Callout type="info" title="Implementation-first">
  All examples reflect real APIs from `@igniter-js/storage`. Verify imports,
  types, and env vars before shipping. If you need to add a new adapter, follow
  the adapter contract and keep business rules out of infra.
</Callout>

## How It Works

Storage centers on two pieces: a manager you configure with scopes, base URL, policies, and hooks; and an adapter that talks to your provider (S3, GCS, custom). You create a manager via the builder, then call `upload`, `list`, `get`, `copy`, or `move` on typed scopes that resolve clean public URLs. Policies guard uploads, hooks feed logs/telemetry, and errors are typed with `IgniterStorageError` so your handlers stay predictable.

## What to Read Next

Start with the [Installation](/docs/storage/\(getting-started\)/installation) and run the [Quick Start](/docs/storage/\(getting-started\)/quick-start) to ship your first upload. Then formalize structure in [Scopes & Paths](/docs/storage/\(core-concepts\)/scopes-and-paths), tighten guardrails in [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation), and add observability in [Hooks & Telemetry](/docs/storage/\(core-concepts\)/hooks-and-telemetry).


---

# S3 Adapter

> Configure the S3 adapter for AWS, MinIO, or any S3-compatible endpoint with public reads.
URL: https://igniterjs.com/docs/storage/s3

## Credentials and Environment

Provide bucket name and credentials via builder or env. Env keys are merged automatically when no explicit credentials are passed.

<TypeTable
  type={{
  IGNITER_STORAGE_S3_BUCKET: {
    type: "string",
    description: "Target bucket for all objects",
    required: true,
  },
  IGNITER_STORAGE_S3_REGION: {
    type: "string",
    description: "AWS region (ignored for some compatibles)",
    required: false,
  },
  IGNITER_STORAGE_S3_ENDPOINT: {
    type: "string",
    description: "Custom endpoint (MinIO/localstack)",
    required: false,
  },
  IGNITER_STORAGE_S3_ACCESS_KEY_ID: {
    type: "string",
    description: "Access key with write permissions",
    required: true,
  },
  IGNITER_STORAGE_S3_SECRET_ACCESS_KEY: {
    type: "string",
    description: "Secret key",
    required: true,
  },
}}
/>

## Minimal Setup

```typescript
import { IgniterStorage } from "@igniter-js/storage";

export const storage = IgniterStorage.create()
  .withAdapter("s3", {
    bucket: process.env.IGNITER_STORAGE_S3_BUCKET!,
    region: process.env.IGNITER_STORAGE_S3_REGION,
    endpoint: process.env.IGNITER_STORAGE_S3_ENDPOINT,
    accessKeyId: process.env.IGNITER_STORAGE_S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.IGNITER_STORAGE_S3_SECRET_ACCESS_KEY,
  })
  .withUrl(process.env.IGNITER_STORAGE_URL || "https://cdn.example.com")
  .build();
```

<Callout type="warn" title="Make the bucket public">
  The adapter attempts to create the bucket and set a public-read policy for objects. Ensure your IAM user can create buckets and apply policies, or pre-create the bucket with a policy that grants `s3:GetObject` on `arn:aws:s3:::<bucket>/*`.
</Callout>

## Local and Compatible Endpoints

* **MinIO/localstack**: Set `IGNITER_STORAGE_S3_ENDPOINT` and keep `tls` disabled for localhost; `forcePathStyle` is enabled by default.
* **CDN URL**: Keep `IGNITER_STORAGE_URL` pointed at your public CDN domain; object keys remain the same.

If you need to avoid ACLs, wrap the adapter and override `put` to remove `public-read`, then serve through signed URLs at the edge.

Continue to [Google Cloud Storage](/docs/storage/\(adapters\)/google-cloud) or review [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation) to restrict uploads.


---

# Architecture

> How the storage builder, manager, scopes, and adapters collaborate to deliver files.
URL: https://igniterjs.com/docs/storage/architecture

## Components

* **Builder**: Immutable chain that registers scopes, adapters, policies, hooks, logger, and telemetry. Produces a configured manager after merging environment input.
* **Manager**: High-level API (`upload`, `list`, `get`, `copy`, `move`, `stream`, `delete`) that resolves paths, enforces policies, triggers hooks, and emits telemetry.
* **Adapter**: Infrastructure-only implementation for S3, GCS, or custom backends. Receives normalized keys and content plus options (`contentType`, `cacheControl`, `public`).
* **Scopes & Paths**: Templates that turn identifiers into paths (`/users/[identifier]` → `/users/123`). Combined with optional `basePath` to isolate environments.

## Flow of an Upload

1. **Resolve**: Manager strips `baseUrl` (if a URL is passed), joins `basePath`, scope, and destination to form the key.
2. **Infer**: Determines filename, extension, and content type (or uses explicit override).
3. **Validate**: Applies policies (size, MIME, extension). Throws `IGNITER_STORAGE_UPLOAD_POLICY_VIOLATION` on failure.
4. **Hooks/Telemetry Start**: Fires `onUploadStarted` and `igniter.storage.upload.started` with attributes.
5. **Replace (optional)**: Deletes matching files when `replace` is set; aborts on failure.
6. **Adapter Write**: Calls adapter `put` with cache control and public flag.
7. **Build Response**: Returns `IgniterStorageFile` with path, URL, name, extension, content type, and optional size.
8. **Hooks/Telemetry End**: Fires success or error hooks and telemetry with durations and codes.

## Env Integration

`IgniterStorageEnv` reads `IGNITER_STORAGE_URL`, `IGNITER_STORAGE_ADAPTER`, `IGNITER_STORAGE_BASE_PATH`, provider creds, and policies. The builder merges env and explicit state, so code config always wins. This keeps environments consistent while letting tests override values locally.

Learn more in [Adapters](/docs/storage/\(adapters\)/index), enforce guardrails in [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation), and instrument behavior in [Hooks & Telemetry](/docs/storage/\(core-concepts\)/hooks-and-telemetry).


---

# File Operations

> Read, list, stream, copy, move, and delete files with predictable keys and URLs.
URL: https://igniterjs.com/docs/storage/file-operations

## Read and Inspect

`get` resolves a relative path or public URL back to storage, returning metadata or `null` when not found. Use it to confirm existence before copying or deleting.

```typescript
const file = await storage.get("public/manual.pdf");
if (!file) {
  return response.notFound({ message: "File missing" });
}
```

## List and Stream

List files under the current base path or a sub-prefix; stream files directly from the adapter when you need to pipe data.

```typescript
const files = await storage.scope("user", "123").list("invoices/");
const stream = await storage.stream(files[0].path);
stream.pipe(res);
```

<Callout type="info">
  Prefixes are resolved relative to the current scope/base path. Passing no
  prefix lists the scope root. Streams come from the adapter; ensure the
  underlying provider supports ranged reads if you need partial responses.
</Callout>

## Copy and Move

Copy or move objects when the adapter implements the operations. If an adapter lacks `copy`/`move`, you receive `IGNITER_STORAGE_COPY_NOT_SUPPORTED` or `IGNITER_STORAGE_MOVE_NOT_SUPPORTED` before any work happens.

```typescript
const receipts = storage.scope("user", "123");
await receipts.copy("invoices/2023.pdf", "invoices/2024.pdf");
await receipts.move("temp/upload.tmp", "assets/upload.pdf");
```

## Delete Safely

```typescript
await storage.delete("public/old-hero.jpg");
```

Deletions emit hooks and telemetry; handle failures with typed errors to retry or report. Combine `list` + `delete` for cleanup jobs, and prefer scoped managers so you never delete outside the intended prefix.

Continue to [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation) to enforce rules, or add observability in [Hooks & Telemetry](/docs/storage/\(core-concepts\)/hooks-and-telemetry).


---

# Hooks & Telemetry

> Observe storage operations with lifecycle hooks and telemetry events for uploads, deletes, copies, and moves.
URL: https://igniterjs.com/docs/storage/hooks-and-telemetry

## Lifecycle Hooks

Register hooks in the builder to react to uploads, deletions, copies, and moves. Hooks receive fully resolved paths plus context about the operation so you can log, validate, or trigger side effects.

```typescript
const storage = IgniterStorage.create()
  .withAdapter("s3", { bucket: "app" })
  .withUrl("https://cdn.app.com")
  .onUploadStarted((payload) => {
    logger.info("upload:start", { path: payload.path, size: payload.size });
  })
  .onUploadSuccess(({ file }) => {
    analytics.track("upload_success", { url: file.url });
  })
  .onDeleteError((ctx, error) => {
    logger.error("delete:error", { path: ctx.path, error });
  })
  .build();
```

Hook payloads include `operation`, `path`, `name`, `extension`, `contentType`, optional `size`, and source details (`file`, `url`, `buffer`, `base64`). Copy/move hooks also receive `from` and `to` paths.

<Callout type="info">
  Hooks run before or after adapter calls depending on the suffix: `Started`
  fires before work, `Success` after completion, and `Error` after a failure. If
  a hook throws in the `Started` phase, the operation is aborted.
</Callout>

## Telemetry Events

Telemetry managers receive typed events (e.g., `igniter.storage.upload.started`, `.success`, `.error`, same for `get`, `list`, `delete`, `copy`, `move`, `stream`). Each event includes attributes like `storage.path`, `storage.size`, `storage.content_type`, durations, and error codes. Pass an `IgniterTelemetryManager` via `.withTelemetry()` to emit to OpenTelemetry or your analytics layer.

```typescript
const storage = IgniterStorage.create()
  .withAdapter("google", { bucket: "cdn-app" })
  .withUrl("https://cdn.app.com")
  .withTelemetry(telemetry)
  .build();
```

## Error Handling

Use `IgniterStorageError.is(error)` to branch on codes (`IGNITER_STORAGE_UPLOAD_FAILED`, `IGNITER_STORAGE_DELETE_FAILED`, `IGNITER_STORAGE_COPY_NOT_SUPPORTED`, etc.). Telemetry emits the same codes so dashboards can surface failing operations quickly.

Continue with provider-specific setup in [Adapters](/docs/storage/\(adapters\)/index) or learn about full lifecycle flows in [Architecture](/docs/storage/\(concepts\)/architecture).


---

# Policies & Validation

> Enforce max file size, allowed MIME types, and extensions before uploads land in your storage bucket.
URL: https://igniterjs.com/docs/storage/policies-and-validation

## Define Policies

Set policies in the builder or via environment variables. Validation runs before uploads, failing fast with `IGNITER_STORAGE_UPLOAD_POLICY_VIOLATION` when a rule is broken.

```typescript
const storage = IgniterStorage.create()
  .withAdapter("s3", { bucket: "app" })
  .withUrl("https://cdn.app.com")
  .withMaxFileSize(10 * 1024 * 1024) // 10 MB
  .withAllowedMimeTypes(["image/png", "image/jpeg"])
  .withAllowedExtensions(["png", "jpg", "jpeg"])
  .build();
```

<TypeTable
  type={{
  maxFileSize: {
    type: "number",
    description: "Maximum bytes allowed; rejected if exceeded",
    required: false,
  },
  allowedMimeTypes: {
    type: "string[]",
    description: "Accepted content types; inferred or explicit",
    required: false,
  },
  allowedExtensions: {
    type: "string[]",
    description: "Accepted extensions (no leading dot)",
    required: false,
  },
}}
/>

<Callout type="info">
  Env equivalents: `IGNITER_STORAGE_MAX_FILE_SIZE`,
  `IGNITER_STORAGE_ALLOWED_MIME_TYPES`, and
  `IGNITER_STORAGE_ALLOWED_EXTENSIONS`. Values merge with builder input;
  undefined values are ignored.
</Callout>

## Handle Violations

```typescript
import { IgniterStorageError } from "@igniter-js/storage";

try {
  await storage.upload(file, "public/avatar.exe");
} catch (error) {
  if (
    IgniterStorageError.is(error) &&
    error.code === "IGNITER_STORAGE_UPLOAD_POLICY_VIOLATION"
  ) {
    const violations = error.data?.violations ?? [];
    return response.badRequest({
      message: "File does not meet requirements",
      violations,
    });
  }
  throw error;
}
```

Violations include `reason`, `message`, and contextual `data` (size or allowed lists). Use them to craft user-facing guidance or logs.

## Checklist

* Provide explicit `contentType` when sending streams so MIME checks work.
* Keep policy defaults consistent across environments by using env vars.
* When replacing files, the same policies apply to the new upload before deletion occurs.

Next: wire observability and lifecycle controls in [Hooks & Telemetry](/docs/storage/\(core-concepts\)/hooks-and-telemetry).


---

# Scopes & Paths

> Model storage hierarchy with global prefixes, typed scopes, and predictable public URLs.
URL: https://igniterjs.com/docs/storage/scopes-and-paths

## Organize Keys with Scopes

Scopes define reusable path templates so uploads stay organized and type-safe. Add scopes in the builder, then call `scope()` to resolve identifiers before uploading or listing files. Use scopes for tenants, users, or public asset roots instead of concatenating strings manually.

```typescript
const storage = IgniterStorage.create()
  .withUrl("https://cdn.myapp.com")
  .withPath("/production")
  .addScope("public", "/public")
  .addScope("user", "/users/[identifier]")
  .build();

const userFiles = storage.scope("user", "u_123");
await userFiles.upload(file, "avatar.png"); // /production/users/u_123/avatar.png
```

<Callout type="info">
  Scopes are typed: when the path includes `[identifier]`, TypeScript requires
  you to pass it. Use scopes everywhere—`upload`, `list`, `copy`, `move`, and
  `delete` all respect the current scope and base path.
</Callout>

## Base Paths and URLs

`withPath()` adds a global prefix (e.g., environment name), while `withUrl()` is the public CDN origin used for URLs. Resolved keys always remove leading slashes and combine base path, scope path, and destination name. You can pass either a relative path or a full URL back to the manager, and it strips the base URL before operating.

```typescript
const prod = storage.path("assets");
await prod.upload(file, "logos/app.svg"); // key: production/assets/logos/app.svg
const url = prod.scope("public").toString; // url generated via baseUrl
```

## Patterns to Reuse

* **Public assets**: `addScope('public', '/public')` for CDNs and marketing files.
* **User content**: `addScope('user', '/users/[identifier]')` to isolate per-user uploads.
* **Transient files**: `addScope('temp', '/temp')` and clean with `list` + `delete` on a schedule.

Continue to [Uploads & Replace](/docs/storage/\(core-concepts\)/uploads-and-replace) to control delivery, or jump to [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation) to enforce sizes and types.


---

# Uploads & Replace

> Deliver files from buffers, URLs, or streams with automatic content-type inference and replace strategies.
URL: https://igniterjs.com/docs/storage/uploads-and-replace

## Upload Entry Points

Use `upload` for File/Blob/Readable streams, `uploadFromUrl` for remote fetch, or `uploadFromBuffer`/`uploadFromBase64` for raw bytes. The manager infers `contentType` from filenames and normalizes cache headers to long-lived public caching by default.

```typescript
// File/Blob
await storage.scope("public").upload(file, "assets/banner.png");

// Remote URL
await storage.uploadFromUrl("https://example.com/logo.svg", "public/logo.svg");

// Buffers
await storage.uploadFromBuffer(Buffer.from(data), "public/report.pdf", {
  contentType: "application/pdf",
});
```

<Callout type="info">
  The manager always resolves the destination key using the current scope and
  base path, even when you pass a full URL back in. Keep your `baseUrl` stable
  so public links remain predictable.
</Callout>

## Replace Strategies

Avoid duplicates by deleting conflicts before uploading. Choose a strategy via `IgniterStorageUploadOptions`:

```typescript
// Replace any file with the same basename (any extension)
await storage.scope("user", "123").upload(file, "avatar.webp", {
  replace: "BY_FILENAME",
});

// Replace only exact filename + extension
await storage.scope("user", "123").upload(file, "resume.pdf", {
  replace: "BY_FILENAME_AND_EXTENSION",
});
```

`BY_FILENAME` removes `avatar.png`, `avatar.jpg`, etc., before saving `avatar.webp`. `BY_FILENAME_AND_EXTENSION` only replaces `resume.pdf`, leaving `resume.docx` untouched. If deletion fails, the upload aborts with `IGNITER_STORAGE_REPLACE_FAILED` so you never end up with half-written state.

## Public Delivery

Uploads set `cacheControl: public, max-age=31536000` and `public: true` when the adapter supports ACLs. Keep your CDN base URL in sync with the bucket permissions (S3 bucket policy or GCS IAM). If you need shorter caching for mutable assets, pass a different `cacheControl` through a custom adapter wrapper.

Next: explore available operations in [File Operations](/docs/storage/\(core-concepts\)/file-operations) and enforce guardrails in [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation).


---

# Installation

> Install @igniter-js/storage, configure credentials, and boot a storage manager with a CDN base URL.
URL: https://igniterjs.com/docs/storage/installation

## Install Dependencies

Use your package manager to add the storage package. Add provider SDKs when you pick an adapter (AWS SDK for S3, `@google-cloud/storage` for GCS).

<Tabs items={["npm", "pnpm", "yarn", "bun"]} groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install @igniter-js/storage @igniter-js/common

    # S3 (optional)
    npm install @aws-sdk/client-s3 @aws-sdk/lib-storage

    # Google Cloud (optional)
    npm install @google-cloud/storage
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @igniter-js/storage @igniter-js/common

    # S3 (optional)
    pnpm add @aws-sdk/client-s3 @aws-sdk/lib-storage

    # Google Cloud (optional)
    pnpm add @google-cloud/storage
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @igniter-js/storage @igniter-js/common

    # S3 (optional)
    yarn add @aws-sdk/client-s3 @aws-sdk/lib-storage

    # Google Cloud (optional)
    yarn add @google-cloud/storage
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @igniter-js/storage @igniter-js/common

    # S3 (optional)
    bun add @aws-sdk/client-s3 @aws-sdk/lib-storage

    # Google Cloud (optional)
    bun add @google-cloud/storage
    ```
  </Tab>
</Tabs>

## Configure Environment

Provide a public CDN/base URL and choose an adapter. You can set credentials in code or environment variables; the builder merges env (`IgniterStorageEnv`) with explicit options.

<TypeTable
  type={{
  IGNITER_STORAGE_URL: {
    type: "string",
    description: "Public base URL for generated file links",
    required: true,
  },
  IGNITER_STORAGE_ADAPTER: {
    type: '"s3" | "google"',
    description: "Adapter key used when no explicit adapter is provided",
    required: false,
  },
  IGNITER_STORAGE_BASE_PATH: {
    type: "string",
    description: 'Optional global prefix (e.g., "/production")',
    required: false,
  },
}}
/>

## Create the Storage Manager

<Steps>
  <Step>
    ### Define a storage service

    ```typescript
    // src/services/storage.ts
    import { IgniterStorage } from '@igniter-js/storage'

    export const storage = IgniterStorage.create()
      .withAdapter('s3', {
        bucket: process.env.IGNITER_STORAGE_S3_BUCKET,
        region: process.env.IGNITER_STORAGE_S3_REGION,
        endpoint: process.env.IGNITER_STORAGE_S3_ENDPOINT,
        accessKeyId: process.env.IGNITER_STORAGE_S3_ACCESS_KEY_ID,
        secretAccessKey: process.env.IGNITER_STORAGE_S3_SECRET_ACCESS_KEY,
      })
      .withUrl(process.env.IGNITER_STORAGE_URL || 'https://cdn.example.com')
      .addScope('public', '/public')
      .build()
    ```

    <Callout type="info">
      Prefer environment variables for credentials. If you omit `.withAdapter()`, set `IGNITER_STORAGE_ADAPTER` and provider env vars so the builder can resolve an adapter automatically.
    </Callout>
  </Step>

  <Step>
    ### Verify connectivity

    ```typescript
    await storage.upload(new Blob(['hello'], { type: 'text/plain' }), 'public/hello.txt')
    const file = await storage.get('public/hello.txt')
    console.log(file?.url)
    ```

    If you see an adapter error or `IGNITER_STORAGE_ADAPTER_NOT_CONFIGURED`, double-check the bucket name, permissions, and `IGNITER_STORAGE_URL`.
  </Step>
</Steps>

## Next Steps

Move to the [Quick Start](/docs/storage/\(getting-started\)/quick-start) to add scopes and return public URLs, then tighten policies in [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation).


---

# Quick Start

> Configure scopes, upload your first file, and return a public URL using @igniter-js/storage.
URL: https://igniterjs.com/docs/storage/quick-start

## Build Your First Upload Path

Follow these steps to configure a manager, add scopes, and serve a public URL in minutes.

<Steps>
  <Step>
    ### Create the storage instance

    ```typescript
    import { IgniterStorage } from '@igniter-js/storage'

    export const storage = IgniterStorage.create()
      .withAdapter('s3', { bucket: 'my-bucket', region: 'us-east-1' })
      .withUrl('https://cdn.myapp.com')
      .addScope('public', '/public')
      .addScope('user', '/users/[identifier]')
      .build()
    ```

    <Callout type="info">
      The builder merges `.withAdapter()` and `.withUrl()` with environment defaults. Scopes become typed: `storage.scope('user', '123').upload(...)` requires the identifier because the path template includes `[identifier]`.
    </Callout>
  </Step>

  <Step>
    ### Upload to a scope

    ```typescript
    const avatar = new Blob(['image-bytes'], { type: 'image/png' })

    const file = await storage
      .scope('user', '123')
      .upload(avatar, 'avatar.png')

    console.log(file.url) // https://cdn.myapp.com/users/123/avatar.png
    ```

    The manager infers content type from the filename and sets public caching (`cache-control: public, max-age=31536000`).
  </Step>

  <Step>
    ### Fetch or clean up

    ```typescript
    const metadata = await storage.get(file.url) // works with URL or relative path
    const listed = await storage.scope('user', '123').list()
    await storage.delete(file.path)
    ```

    Use `list` for inventories and `delete` for cleanups. If you need to reorganize files, use `copy` or `move` (adapter support required).
  </Step>
</Steps>

## Handle Errors Early

Wrap uploads with typed errors to present helpful messages:

```typescript
import { IgniterStorageError } from "@igniter-js/storage";

try {
  await storage.upload(file, "public/banner.pdf");
} catch (error) {
  if (IgniterStorageError.is(error)) {
    // Guardrails
    if (error.code === "IGNITER_STORAGE_UPLOAD_POLICY_VIOLATION") {
      return response.badRequest({
        message: "File does not meet requirements",
      });
    }

    return response.error({ message: error.message });
  }

  throw error;
}
```

## Next Steps

Design your hierarchy in [Scopes & Paths](/docs/storage/\(core-concepts\)/scopes-and-paths), set size/type guardrails in [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation), and add lifecycle hooks in [Hooks & Telemetry](/docs/storage/\(core-concepts\)/hooks-and-telemetry).


---

# Migrations & Cleanup

> Move, copy, and delete files safely during restructures, environment changes, or retention jobs.
URL: https://igniterjs.com/docs/storage/migrations-and-cleanup

## Reorganize Paths

When you rename folders or change scope structures, use `copy` or `move` with scoped managers. This keeps base paths intact and reduces accidental cross-tenant moves.

```typescript
const legacy = storage.path("legacy");
await legacy.copy("images/logo.png", "images/logo.v2.png");
await legacy.move("temp/upload.tmp", "public/uploads/upload.pdf");
```

If the adapter does not support copy/move, you will receive `IGNITER_STORAGE_COPY_NOT_SUPPORTED` or `IGNITER_STORAGE_MOVE_NOT_SUPPORTED` before any changes occur.

## Environment Transitions

Switch `withPath` to migrate between environments (e.g., `/staging` → `/production`) without renaming files. Populate the new prefix by copying critical assets, then cut traffic by updating `IGNITER_STORAGE_URL` to the new CDN domain if needed.

## Cleanup Jobs

Combine `list` and `delete` for retention policies:

```typescript
const temp = storage.scope("public").path("temp");
const files = await temp.list();
await Promise.all(files.map((f) => temp.delete(f.path)));
```

Run these jobs with observability: hooks emit success/error events per deletion, and telemetry attributes (`storage.path`, `storage.duration_ms`, `storage.error.code`) keep dashboards honest.

For more on operations, see [File Operations](/docs/storage/\(core-concepts\)/file-operations) and [Hooks & Telemetry](/docs/storage/\(core-concepts\)/hooks-and-telemetry).


---

# Serving Public Assets

> Publish static assets with predictable URLs, long-lived caching, and clear folder structure.
URL: https://igniterjs.com/docs/storage/serving-public-assets

## Structure Public Assets

Keep public files under a dedicated scope for clean URLs and cache control. Pair a global `basePath` for environment separation with a `public` scope.

```typescript
const storage = IgniterStorage.create()
  .withAdapter("s3", { bucket: "cdn-app" })
  .withUrl("https://cdn.app.com")
  .withPath("/production")
  .addScope("public", "/public")
  .build();
```

Upload assets with descriptive paths:

```typescript
await storage.scope("public").upload(heroImage, "marketing/hero.webp");
await storage.scope("public").upload(logoSvg, "brand/logo.svg");
```

## Caching and Invalidations

Uploads default to `public, max-age=31536000`. Version assets by filename to avoid breaking caches (`hero.v2.webp`) and keep old assets until safe to delete. If you need rapid changes, use a shorter `cacheControl` in a thin adapter wrapper or serve through a CDN with cache invalidation.

## Link Building

Use the returned `url` directly in frontend code or CMS entries. Because URLs are derived from `baseUrl + basePath + scope`, migrations are minimal: update `withPath('/staging')` and keep the same asset names. Cross-link with [Scopes & Paths](/docs/storage/\(core-concepts\)/scopes-and-paths) for hierarchy tips and [Policies](/docs/storage/\(core-concepts\)/policies-and-validation) to block unsafe file types.


---

# Streaming & Large Files

> Stream files, handle large uploads, and apply retries safely on S3 or GCS.
URL: https://igniterjs.com/docs/storage/streaming-and-large-files

## Stream Reads

Use `stream` to pipe files directly from the adapter to HTTP responses or processing pipelines.

```typescript
const stream = await storage.stream("public/video.mp4");
stream.pipe(res);
```

Ensure your adapter/provider supports ranged requests if you need partial content; otherwise serve full streams.

## Large Uploads

The S3 adapter leverages multipart uploads when given Node streams, making large uploads resilient. Always set or infer `contentType` for correct policies and downstream behavior. Consider a preflight check on size if the source is known before streaming.

```typescript
await storage.scope("public").upload(largeStream, "backups/db.dump", {
  replace: undefined,
});
```

<Callout type="info">
  If you need client-side chunking, keep that logic at the edge and hand a
  single stream or Blob to the storage manager. Policies still run before
  upload, and errors return `IGNITER_STORAGE_UPLOAD_FAILED` with the original
  cause.
</Callout>

## Retry and Backoff

Wrap uploads with retry logic for transient network failures, but avoid retrying policy violations. Typed errors expose `code` and `operation` so you can branch cleanly.

```typescript
import { IgniterStorageError } from "@igniter-js/storage";

async function uploadWithRetry(
  file: Blob,
  destination: string,
  maxRetries = 3,
) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await storage.upload(file, destination);
    } catch (error) {
      if (IgniterStorageError.is(error)) {
        if (error.code === "IGNITER_STORAGE_UPLOAD_POLICY_VIOLATION")
          throw error;
        if (attempt === maxRetries) throw error;
      }
      await new Promise((resolve) => setTimeout(resolve, attempt * 500));
    }
  }
}
```

See [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation) for size/type guardrails and [File Operations](/docs/storage/\(core-concepts\)/file-operations) for more lifecycle actions.


---

# User-Generated Content

> Safely store user uploads with scoped paths, replace strategies, and strict policies.
URL: https://igniterjs.com/docs/storage/user-generated-content

## Scope Per User or Tenant

Keep uploads isolated with identifier scopes. This prevents cross-tenant collisions and makes cleanup straightforward.

```typescript
const userStorage = storage.scope("user", user.id);
await userStorage.upload(file, "avatar.png");
await userStorage.upload(document, "documents/contract.pdf");
```

## Enforce Guardrails

Combine policies and replace strategies to control what lands in your bucket.

```typescript
const storage = IgniterStorage.create()
  .withAdapter("s3", { bucket: "ugc" })
  .withUrl("https://cdn.app.com")
  .withMaxFileSize(5 * 1024 * 1024)
  .withAllowedMimeTypes(["image/png", "image/jpeg", "application/pdf"])
  .withAllowedExtensions(["png", "jpg", "jpeg", "pdf"])
  .build();

await storage.scope("user", user.id).upload(photo, "avatar.png", {
  replace: "BY_FILENAME",
});
```

`BY_FILENAME` keeps only one avatar per user regardless of format; policies reject oversized or unsafe files before upload.

## Moderate and Move

Use `list` to review pending uploads, then `copy` or `move` into approved locations after moderation. If an adapter lacks copy/move support, you will get a typed error before any files change, allowing you to fall back to download/re-upload logic.

Link to [Uploads & Replace](/docs/storage/\(core-concepts\)/uploads-and-replace) for delivery options and [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation) for stricter rules.


---

# API Reference

> Quick reference for the storage builder, manager methods, and upload options.
URL: https://igniterjs.com/docs/storage/api-reference

## Builder

<TypeTable
  type={{
  "withAdapter(adapterOrKey, credentials?)": {
    type: "IgniterStorageBuilder",
    description: "Set adapter instance or key + credentials",
  },
  "withAdapterFactories(factories)": {
    type: "IgniterStorageBuilder",
    description: "Register custom adapter factories keyed by string",
  },
  "withUrl(url)": {
    type: "IgniterStorageBuilder",
    description: "Set public base URL for generated links",
  },
  "withPath(basePath)": {
    type: "IgniterStorageBuilder",
    description: "Add a global prefix for all keys",
  },
  "withMaxFileSize(bytes)": {
    type: "IgniterStorageBuilder",
    description: "Set max upload size policy",
  },
  "withAllowedMimeTypes(list)": {
    type: "IgniterStorageBuilder",
    description: "Restrict uploads by MIME type",
  },
  "withAllowedExtensions(list)": {
    type: "IgniterStorageBuilder",
    description: "Restrict uploads by extension",
  },
  "addScope(key, path?)": {
    type: "IgniterStorageBuilder",
    description: 'Register typed scope; path defaults to "/<key>"',
  },
  "withLogger(logger)": {
    type: "IgniterStorageBuilder",
    description: "Inject logger used by manager",
  },
  "withTelemetry(manager)": {
    type: "IgniterStorageBuilder",
    description: "Emit typed telemetry events",
  },
  "build()": {
    type: "IgniterStorageManager",
    description: "Create a manager with merged env + builder state",
  },
}}
/>

## Manager Methods

<TypeTable
  type={{
  "path(prefix)": {
    type: "IgniterStorageManager",
    description: "Append a path segment and return a new scoped manager",
  },
  "scope(key, identifier?)": {
    type: "IgniterStorageManager",
    description:
      "Bind to a registered scope; identifier required when path includes [identifier]",
  },
  "upload(file, destination, options?)": {
    type: "Promise<IgniterStorageFile>",
    description: "Upload Blob/File/Readable with optional replace strategy",
  },
  "uploadFromUrl(url, destination, options?)": {
    type: "Promise<IgniterStorageFile>",
    description: "Fetch a remote URL then upload to destination",
  },
  "uploadFromBuffer(buffer, destination, options?)": {
    type: "Promise<IgniterStorageFile>",
    description: "Upload bytes with optional contentType",
  },
  "uploadFromBase64(base64, destination, options?)": {
    type: "Promise<IgniterStorageFile>",
    description: "Upload base64 data; contentType optional",
  },
  "get(pathOrUrl)": {
    type: "Promise<IgniterStorageFile | null>",
    description: "Check existence and return metadata",
  },
  "list(prefix?)": {
    type: "Promise<IgniterStorageFile[]>",
    description: "List files under the current scope/base path",
  },
  "stream(pathOrUrl)": {
    type: "Promise<Readable>",
    description: "Open a readable stream for a file",
  },
  "delete(pathOrUrl)": {
    type: "Promise<void>",
    description: "Delete a file",
  },
  "copy(from, to)": {
    type: "Promise<IgniterStorageFile>",
    description: "Copy a file; adapter must support copy",
  },
  "move(from, to)": {
    type: "Promise<IgniterStorageFile>",
    description: "Move a file; adapter must support move",
  },
}}
/>

## Upload Options

<TypeTable
  type={{
  replace: {
    type: '"BY_FILENAME" | "BY_FILENAME_AND_EXTENSION"',
    description:
      "Delete matching files before upload; aborts upload on deletion failure",
    required: false,
  },
}}
/>

For errors and recovery patterns, see [Error Codes](/docs/storage/\(reference\)/error-codes) and [Troubleshooting](/docs/storage/troubleshooting). For concepts and flows, visit [Architecture](/docs/storage/\(concepts\)/architecture).


---

# Error Codes

> Reference for Igniter Storage error codes and how to fix them.
URL: https://igniterjs.com/docs/storage/error-codes

## Operational Errors

* `IGNITER_STORAGE_ADAPTER_NOT_CONFIGURED`: No adapter configured or factory missing. Set `.withAdapter(...)` or `IGNITER_STORAGE_ADAPTER` and credentials.
* `IGNITER_STORAGE_INVALID_SCOPE`: Scope key not registered. Add it in the builder or correct typos.
* `IGNITER_STORAGE_SCOPE_IDENTIFIER_REQUIRED`: Scope requires an identifier; pass it to `scope(key, id)`.
* `IGNITER_STORAGE_INVALID_PATH_HOST`: Path URL host differs from `baseUrl`. Ensure you call `get/delete/list` with URLs matching your configured `baseUrl`.

## Upload Failures

* `IGNITER_STORAGE_UPLOAD_POLICY_VIOLATION`: File failed size/type/extension checks. Adjust policies or the file.
* `IGNITER_STORAGE_UPLOAD_FAILED`: Adapter or network failure during upload. Inspect `cause` and retry with backoff.
* `IGNITER_STORAGE_REPLACE_FAILED`: Replace strategy could not delete conflicting files; clean manually or adjust permissions.
* `IGNITER_STORAGE_FETCH_FAILED`: `uploadFromUrl` could not retrieve the source; verify network and URL.

## File Operations

* `IGNITER_STORAGE_DELETE_FAILED`, `IGNITER_STORAGE_LIST_FAILED`, `IGNITER_STORAGE_STREAM_FAILED`, `IGNITER_STORAGE_GET_FAILED`: Provider issue or permissions. Check credentials, bucket policy, and path correctness.
* `IGNITER_STORAGE_COPY_NOT_SUPPORTED` / `IGNITER_STORAGE_MOVE_NOT_SUPPORTED`: Adapter lacks copy/move; implement in the adapter or fall back to download + upload.
* `IGNITER_STORAGE_COPY_FAILED` / `IGNITER_STORAGE_MOVE_FAILED`: Provider error during copy/move. Retry or perform manual relocation.

For troubleshooting steps and quick checks, see [Troubleshooting](/docs/storage/troubleshooting). To instrument and catch these early, enable [Hooks & Telemetry](/docs/storage/\(core-concepts\)/hooks-and-telemetry).


---

# Testing & Local Dev

> Test storage flows with mock adapters, local S3/GCS emulators, and clean fixtures.
URL: https://igniterjs.com/docs/storage/testing-and-local-dev

## Mock Adapter for Unit Tests

Use the built-in mock adapter to avoid network calls. It implements the storage contract and stores data in memory, making it ideal for unit tests.

```typescript
import { IgniterStorage } from "@igniter-js/storage";
import { IgniterMockStorageAdapter } from "@igniter-js/storage/adapters/mock.adapter";

const storage = IgniterStorage.create()
  .withAdapter(new IgniterMockStorageAdapter())
  .withUrl("http://localhost:3000/cdn")
  .addScope("test", "/tests")
  .build();
```

Reset the adapter between tests to prevent bleed-over:

```typescript
afterEach(() => storage.adapter.clear());
```

## Local Emulators

* **S3 (MinIO/localstack)**: set `IGNITER_STORAGE_S3_ENDPOINT=http://127.0.0.1:9000`, keep `forcePathStyle` (default) and disable TLS for localhost. Seed buckets before tests.
* **GCS emulator**: set `IGNITER_STORAGE_GOOGLE_ENDPOINT` to the emulator URL and provide a test service account.

## Fixtures and Cleanup

Use scoped managers to limit cleanup radius. Combine `list` + `delete` after each suite to keep fixtures small. Hooks fire during tests, so assert on emitted events to verify observability.

For troubleshooting common adapter errors, see [Troubleshooting](/docs/storage/troubleshooting). For production readiness, review [Policies & Validation](/docs/storage/\(core-concepts\)/policies-and-validation).


---


# Changelog

Version updates and release notes

---

# v0.1.1 - Initial Release

> The first release of Igniter.js, introducing the core framework features.
URL: https://igniterjs.com/changelog/v0.1.1

Released on February 26, 2025

## Initial Release

Welcome to Igniter.js! This is the first public release of the framework.

### Core Features

* **Type-Safe Router**: Procedure-based routing system with middleware support
* **Controller Actions**: Type-safe controller actions with request/response handling
* **Procedure System**: Middleware chain with execution control and context injection
* **Error Handling**: Built-in error handling and response processing

### Getting Started

```bash
npm install @igniter-js/core
```

Check out our [Getting Started Guide](/docs/core/quick-start) to begin building with Igniter.js.


---

# v0.1.13 - React Cache & API Improvements

> Added React cache support and various API improvements.
URL: https://igniterjs.com/changelog/v0.1.13

Released on February 28, 2025

## Features

* **React Cache**: Added React cache support for better client-side caching
* **API Improvements**: Various improvements to the API for better developer experience

This release focused on improving the client-side experience with React cache integration and general API enhancements.


---

# v0.1.14 - Client Error Processing Fix

> Fixed client error processing issues.
URL: https://igniterjs.com/changelog/v0.1.14

Released on March 4, 2025

## Bug Fixes

* **Client Error Processing**: Fixed client error processing issues

Resolved issues with how client errors were being processed and handled.


---

# v0.1.15 - Client Error Fix

> Fixed client error on request processor.
URL: https://igniterjs.com/changelog/v0.1.15

Released on March 7, 2025

## Bug Fixes

* **Client Error**: Fixed client error on request processor

Resolved an issue where the client was encountering errors when processing requests through the request processor.


---

# v0.1.16 - Response Logging Fix

> Removed debug logs from response processing.
URL: https://igniterjs.com/changelog/v0.1.16

Released on March 8, 2025

## Bug Fixes

* **Response Logging**: Removed debug logs from response processing

Cleaner console output by removing unnecessary debug logs from response processing.


---

# v0.1.17 - URL Parameter Support

> Added support for URL parameters in the request processor call method.
URL: https://igniterjs.com/changelog/v0.1.17

Released on March 15, 2025

## Features

* **URL Parameters**: Added support for URL parameters in `call` method of request processor

This enhancement allows you to pass URL parameters directly when calling procedures, making it easier to work with dynamic routes.


---

# v0.1.18 - Request Processor Improvements

> Minor update fixing request processor input parameter handling.
URL: https://igniterjs.com/changelog/v0.1.18

Released on March 15, 2025

## Bug Fixes

* **Request Processor**: Made input parameter optional in request processor method

This was a minor bug fix release that improves the flexibility of the request processor by making the input parameter optional.


---

# v0.2.0-alpha.0 - Modular Architecture & Real-Time Support

> Major release introducing modular adapters, real-time capabilities, build-time extraction, and Turborepo migration.
URL: https://igniterjs.com/changelog/v0.2.0-alpha.0

Released on June 30, 2025

## Major Features

### Modular Architecture

Igniter.js is now a fully modular, type-safe backend framework. This alpha release debuts a robust architecture with first-class type safety, powerful built-in features, and standalone adapters for extensibility and flexibility.

### Adapters Extracted to Standalone Packages

All adapters are now standalone packages:

* `@igniter-js/adapter-redis` - Redis adapter for caching and pub/sub
* `@igniter-js/adapter-bullmq` - BullMQ adapter for background jobs
* `@igniter-js/adapter-opentelemetry` - OpenTelemetry adapter for telemetry
* `@igniter-js/adapter-mcp-server` - MCP Server adapter for AI integrations

### Real-Time System

* **Type-Safe Events**: Type-safe, context-aware event publishing and subscription
* **Server-Sent Events**: Built-in SSE processor with automatic client management
* **Channel-Based**: Channel-based, namespaced communication with fine-grained access control
* **Automatic Reconnection**: Automatic reconnection and event replay for reliable delivery
* **Strongly-Typed**: Strongly-typed event payloads and handler signatures

### Build-Time Extraction

* **Zero Bundle Contamination**: Resolved bundle contamination (2.3MB → 45KB)
* **Schema-Based Client**: Create schema-based client that eliminates bundle contamination
* **Type-Safe Client**: Generate type-safe client with zero server code contamination
* **Framework Detection**: Automatic framework detection and auto-configuration

### Turborepo Migration

Migrated repository to Turborepo monorepo structure for better build performance and developer experience.

## Breaking Changes

* **New Modular Package Architecture**: Adapters extracted into standalone packages
* **Updated Import Paths**: Updated import paths and API patterns
* **Client-Side Proxy**: Implemented client-side proxy to prevent handler execution

## Bug Fixes

* Fixed client error handling in createFetcher
* Fixed response processor to return structured error format
* Fixed request processor to handle optional middleware use array
* Fixed client environment detection and bundling issues
* Added 'use client' directive to igniter.client.ts to resolve Next.js error

## Documentation

* Complete rewrite of README.md
* Added comprehensive guides for all starter applications
* Added MCP adapter documentation

## Installation

```bash
# Core framework
npm install @igniter-js/core

# Choose the adapters you need
npm install @igniter-js/adapter-redis ioredis
npm install @igniter-js/adapter-bullmq bullmq
npm install @igniter-js/adapter-opentelemetry
npm install @igniter-js/adapter-mcp-server
```

## Links

* [Getting Started](/docs/core/quick-start)
* [Adapters Documentation](/docs/store)


---

# v0.2.61 - CLI Improvements

> CLI improvements with esbuild integration and better build performance.
URL: https://igniterjs.com/changelog/v0.2.61

Released on August 20, 2025

## Features

* **ESBuild Integration**: Added esbuild dependency for better build performance
* **CLI Improvements**: Various improvements to the CLI tooling

This release focused on improving the CLI experience and build performance.


---

# v0.2.62 - Core Improvements

> Various core improvements and bug fixes.
URL: https://igniterjs.com/changelog/v0.2.62

Released on August 20, 2025

## Features

* **Core Improvements**: Various improvements to the core framework
* **Bug Fixes**: Fixed several issues in the core framework

This release focused on improving the stability and performance of the core framework.


---

# v0.2.65 - CLI Improvements & Logging System

> Major CLI improvements with interactive wizard, enhanced logging system, and better Windows support.
URL: https://igniterjs.com/changelog/v0.2.65

Released on August 20, 2025

## Features

### CLI Enhancements

* **Interactive Wizard**: Added interactive wizard for `generate feature` command
* **Timeline Progress**: Improved visual feedback with timeline-based progress tracking
* **Prisma Provider**: Enhanced Prisma provider and framework detection
* **Windows Support**: Fixed TSX loader execution on Windows for schema generation
* **Debug Mode**: Added debug mode support to CLI logging system
* **ESBuild Integration**: Added esbuild dependency for better build performance

### Logging System

* **Configurable Levels**: Enhanced logging system with configurable levels and context
* **Better Integration**: Improved telemetry integration and performance
* **Logging Context**: Added context-aware logging for better debugging

### Core Improvements

* **Client Hooks**: Optimized client hooks with stable parameters and prevent unnecessary re-renders
* **Builder Service**: Improved builder service docs configuration and middleware execution
* **NextFunction**: Added `NextFunction` interface and enhanced procedure context with `next()` support
* **JSON Detection**: Improved JSON content-type detection in response processor

## Bug Fixes

* Fixed client hooks to prevent unnecessary re-renders
* Fixed builder service docs configuration
* Fixed TSX loader execution on Windows
* Fixed JSON content-type detection

## Documentation

* Updated core concepts documentation
* Cleaned up menu structure
* Added comprehensive test coverage for build adapters and OpenAPI integration

## Links

* [CLI Docs](/docs/core/installation)
* [Logging System](/docs/core/installation)


---

# v0.2.68 - MCP Server Enhancements

> Enhanced MCP server with comprehensive tooling, improved URL generation, and better context handling.
URL: https://igniterjs.com/changelog/v0.2.68

Released on August 29, 2025

## Features

### MCP Server Enhancements

* **Comprehensive Tooling**: Enhanced MCP server with improved diagnostics and tool management
* **URL Generation**: Enhanced URL generation with query parameter support
* **Status Field**: Added `status` field to `IgniterProcessorResponse` for better response handling
* **Context Handling**: Improved context parsing and reassignment for body and query parameters

### Developer Experience

* **MCP Server Configuration**: Added MCP Server configuration and custom rules to all starter templates
* **Repository Structure**: Consolidated agent instructions and cleanup structure
* **Documentation**: Restructured MCP server documentation with practical approach

## Bug Fixes

* Fixed context parsing to ensure parsed body and query are reassigned to context
* Fixed security and path handling in docs and process spawning

## Documentation

* Enhanced MCP server documentation with conversational approach
* Added comprehensive MCP server integration guide
* Updated starter templates with MCP Server configuration examples

## Links

* [MCP Server Docs](/docs/mcp-server)
* [Starter Templates](/templates)


---

# v0.2.69 - Bug Fixes

> Minor bug fixes and improvements.
URL: https://igniterjs.com/changelog/v0.2.69

Released on October 22, 2025

## Bug Fixes

* Various minor bug fixes and stability improvements

This was a patch release focusing on bug fixes and stability improvements.


---

# v0.2.70 - Type Safety & Build Improvements

> Fixed type inference issues and improved CLI build dependencies.
URL: https://igniterjs.com/changelog/v0.2.70

Released on October 22, 2025

## Bug Fixes

* **Type Inference**: Fixed type inference for server caller with `InferServerRouterCaller`
* **Duplicate Types**: Removed duplicate type intersection in `InferServerRouterCallerAction`
* **CLI Dependencies**: Added chalk and supports-color to esbuild external dependencies
* **Post-Build Script**: Added post-build script to inject 'use client' directive automatically

## 🔧 Improvements

* **Build Process**: Improved build process with better dependency handling
* **Type Safety**: Enhanced type safety across the framework


---

# v0.3.0 - Breaking Changes & Major Improvements

> Major release introducing breaking changes, MCP adapter refactoring, new Bot package, and significant improvements to type safety and developer experience.
URL: https://igniterjs.com/changelog/v0.3.0

Released on October 22, 2025

## Major Features

### MCP Adapter API Refactoring

The MCP adapter has been completely refactored for better type safety and developer experience:

* **New Function Signature**: Changed from `createMcpAdapter(router, options)` to `createMcpAdapter(options)` where `router` is now a required property in the options object
* **Automatic Context Inference**: The `context` function option has been removed. Context is now automatically inferred from the router's built-in context
* **Custom Prompts**: Register prompts that AI agents can use to guide interactions
* **Custom Resources**: Expose resources that AI agents can read
* **OAuth Authorization**: First-class support for OAuth-based authorization with automatic Bearer token verification

### New Bot Package

Introducing `@igniter-js/bot` - a comprehensive package for building chatbots with adapters for Telegram and WhatsApp:

* Type-safe bot adapters
* Command handling system
* Message types and middleware support
* Comprehensive documentation and examples

### Core Improvements

* **Improved Type Inference**: Enhanced type inference for server caller with `InferServerRouterCaller`
* **Builder Pattern API**: Updated API to use builder pattern consistently
* **Request Raw Access**: Added `request.raw` access in controller actions
* **Caller Property**: Added `caller` property to router (replacing `$caller`)
* **Procedure Context**: Improved procedure context with better type inference

## Breaking Changes

### MCP Adapter Migration

If you're using the MCP adapter, you'll need to update your code:

```typescript
// Before (v0.2.x)
const handler = createMcpAdapter(AppRouter, {
  serverInfo: { name: 'My Server', version: '1.0.0' },
  context: (req) => ({
    context: { user: 'test' },
    tools: [],
    request: req,
    timestamp: Date.now()
  })
});

// After (v0.3.x)
const handler = createMcpAdapter({
  router: AppRouter,
  serverInfo: { name: 'My Server', version: '1.0.0' },
  // context is automatically inferred!
});
```

### Caller Property Rename

The `$caller` property has been renamed to `caller`:

```typescript
// Before
const result = await router.$caller({}).action();

// After
const result = await router.caller({}).action();
```

### Middleware Removal

Middlewares have been removed from the Igniter Builder. Use procedures with middleware instead.

## Bug Fixes

* Fixed CLI schema generation errors by externalizing dependencies
* Fixed ESM require errors in CLI bin file
* Fixed `noContent()` to return HTTP 204 with empty body per RFC 7231
* Fixed TypeScript type errors in adapter-mcp-server
* Fixed duplicate type intersections in `InferServerRouterCallerAction`
* Fixed args property naming and ZodRawShape format

## Documentation

* Updated README and AGENT.md to reflect new builder pattern API
* Added comprehensive MCP Adapter documentation
* Updated client usage documentation
* Added Bot package documentation

## Links

* [MCP Adapter Docs](/docs/mcp-server)
* [Bot Package Docs](/docs/bots)


---


# Learn Course

Step-by-step tutorials to master Igniter.js

---

# 01: Creating Your Project

> Use the Igniter.js CLI to scaffold a production-ready Next.js application
URL: https://igniterjs.com/learn/course/01-creating-your-project

<ChapterObjectives
  objectives={[
  { text: "Understand the Igniter.js CLI and its capabilities" },
  { text: "Create a new project using the interactive setup wizard" },
  { text: "Configure your project with the right features and providers" },
  { text: "Explore the generated project structure" },
  { text: "Run your first development server" }
]}
/>

## The Igniter.js CLI

The **Igniter.js CLI** is your best friend for building applications with Igniter.js. It's a powerful command-line tool that:

* 🏗️ **Scaffolds new projects** with interactive setup
* 🔄 **Generates features** automatically from Prisma schemas
* 📝 **Creates controllers and procedures** with proper structure
* 🔍 **Generates TypeScript client** and OpenAPI docs automatically
* 🚀 **Runs development server** with hot-reload and interactive dashboard

Think of it as your personal assistant that handles all the boilerplate so you can focus on building features.

## Creating Your Project

Let's create your link shortening SaaS! Open your terminal and run:

```bash
npx @igniter-js/cli init shortify
```

This command launches an **interactive setup wizard** that will guide you through configuring your project.

<Callout type="info" title="Using a different package manager?">
  The CLI works with any package manager:

  * **npm**: `npx @igniter-js/cli init shortify`
  * **pnpm**: `pnpx @igniter-js/cli init shortify`
  * **yarn**: `yarn dlx @igniter-js/cli init shortify`
  * **bun**: `bunx @igniter-js/cli init shortify`
</Callout>

## Interactive Setup Wizard

The CLI will ask you a series of questions to customize your project. Here's what to choose for our SaaS:

### 1. **Select a Framework**

```
? Which framework would you like to use?
  ❯ Next.js (Recommended for full-stack apps)
    Vite (For frontend + separate API)
    Remix
    Express
    Tanstack Start
```

**Choose: Next.js** - It's perfect for full-stack applications and gives us Server Components, API Routes, and excellent TypeScript support.

### 2. **Choose Your Database**

```
? Which database would you like to use?
  ❯ PostgreSQL (Recommended for production)
    MySQL
    SQLite (For development only)
    None (I'll set it up later)
```

**Choose: PostgreSQL** - It's robust, scalable, and has excellent Prisma support. We'll use a free hosted instance later.

### 3. **Select Your ORM**

```
? Which ORM would you like to use?
  ❯ Prisma (Recommended - Type-safe, great DX)
    Drizzle
    None
```

**Choose: Prisma** - Best developer experience, auto-generated types, and amazing tooling.

### 4. **Choose Features**

```
? Select the features you want to enable (use space to select):
  ◯ Store (Redis caching)
  ◯ Jobs (Background task processing with BullMQ)
  ◯ Logging (Structured logging)
  ◯ Telemetry (OpenTelemetry for monitoring)
```

**For now, let's start simple and select:**

* ✅ **Logging** - Essential for debugging
* ✅ **Telemetry** - Good to have from the start

We'll add Store and Jobs later when we implement analytics and background processing.

### 5. **Package Manager**

```
? Which package manager would you like to use?
  ❯ npm
    pnpm
    yarn
    bun
```

**Choose your preferred package manager** - I recommend **pnpm** or **bun** for faster installs, but **npm** works perfectly fine too.

### 6. **Additional Options**

```
? Would you like to initialize a Git repository? (Y/n)
? Would you like to set up Docker Compose? (Y/n)
? Would you like to install dependencies now? (Y/n)
```

* **Git**: ✅ Yes (essential for version control)
* **Docker Compose**: ❌ No (we'll use cloud services)
* **Install dependencies**: ✅ Yes (saves time)

## What Just Happened?

After you complete the wizard, the CLI will:

1. ✨ **Create your project directory** (`shortify/`)
2. 📦 **Generate all necessary files** (configuration, boilerplate, etc.)
3. 🔧 **Configure your selected features**
4. 📥 **Install all dependencies**
5. 🎯 **Initialize a Git repository**
6. 🎉 **Display next steps**

You'll see output like this:

```bash
✔ Project created successfully!
✔ Dependencies installed
✔ Git repository initialized

🎉 Your Igniter.js project is ready!

📁 Project: shortify
🚀 Framework: Next.js
💾 Database: PostgreSQL (Prisma)
✨ Features: Logging, Telemetry

Next steps:
  1. cd shortify
  2. Copy .env.example to .env and configure your environment
  3. Run 'npm run dev' to start the development server

Happy building! 🔥
```

## Exploring Your Project

Let's navigate into your new project and explore what was generated:

```bash
cd shortify
```

Here's the structure you'll see:

<Files>
  <Folder name="shortify" defaultOpen>
    <Folder name="src" defaultOpen>
      <Folder name="app">
        <File name="layout.tsx" />

        <File name="page.tsx" />

        <Folder name="api">
          <Folder name="[[...igniter]]">
            <File name="route.ts" />
          </Folder>
        </Folder>
      </Folder>

      <Folder name="features">
        <Folder name="example">
          <Folder name="controllers">
            <File name="example.controller.ts" />
          </Folder>
        </Folder>
      </Folder>

      <Folder name="services">
        <File name="logger.ts" />

        <File name="telemetry.ts" />
      </Folder>

      <File name="igniter.ts" />

      <File name="igniter.context.ts" />

      <File name="igniter.router.ts" />

      <File name="igniter.client.ts" />
    </Folder>

    <Folder name="prisma">
      <File name="schema.prisma" />
    </Folder>

    <File name=".env.example" />

    <File name="package.json" />

    <File name="next.config.ts" />

    <File name="tsconfig.json" />
  </Folder>
</Files>

### Key Files Explained

Let's understand what each important file does:

**`src/igniter.ts`**
The main Igniter.js instance. This is where you configure all your features, adapters, and plugins.

```typescript
// This file was generated with your selected features
export const igniter = Igniter
  .context(createIgniterAppContext())
  .logger(logger)           // ← You selected Logging
  .telemetry(telemetry)     // ← You selected Telemetry
  .config({
    baseURL: 'http://localhost:3000',
    basePATH: '/api/v1',
  })
  .create()
```

**`src/igniter.router.ts`**
Your API router. All controllers are registered here.

```typescript
export const AppRouter = igniter.router({
  controllers: {
    example: exampleController, // ← Example controller
    // Your new controllers will be added here
  },
})
```

**`src/app/api/[[...igniter]]/route.ts`**
The Next.js API route that connects Igniter.js to Next.js. This is the magic glue!

**`prisma/schema.prisma`**
Your database schema. We'll design our tables here in the next chapter.

<Quiz
  question="What does the Igniter.js CLI do when you run 'init'?"
  options={[
  { label: "Only creates a package.json file", value: "package" },
  { label: "Downloads a pre-built template without customization", value: "template" },
  { label: "Runs an interactive wizard and generates a customized project structure", value: "wizard", isCorrect: true },
  { label: "Just installs Igniter.js as a dependency", value: "install" }
]}
  explanation="The CLI runs an interactive setup wizard that asks you about your framework, database, features, and preferences, then generates a fully customized project structure based on your answers."
/>

## Setting Up Environment Variables

Before running your project, you need to configure environment variables. The CLI created an `.env.example` file with all the variables you need.

Copy it to create your local environment file:

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

Now open `.env` in your code editor. You'll see something like:

```bash
# Database
DATABASE_URL="postgresql://user:password@localhost:5432/shortify?schema=public"

# Next.js
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Igniter.js
NEXT_PUBLIC_IGNITER_API_URL="http://localhost:3000"
NEXT_PUBLIC_IGNITER_API_BASE_PATH="/api/v1"
```

<Callout type="warn" title="Don't worry about the database yet!">
  We'll set up a free PostgreSQL database in the next chapter. For now, you can leave the `DATABASE_URL` as is - we won't be using the database yet.
</Callout>

## Running Your Development Server

Now for the exciting part - let's start your application! Run:

```bash
npm run dev
```

This command does three things:

1. 🔄 Starts the Next.js development server
2. 🔥 Starts Igniter.js with hot-reload
3. 🎯 Opens Igniter Studio (interactive API dashboard)

You'll see output like:

```bash
▲ Next.js 15.0.0
  - Local:        http://localhost:3000
  - Network:      http://192.168.1.100:3000

🔥 Igniter.js
  ✓ Router loaded successfully
  ✓ 1 controller registered (example)
  ✓ 1 endpoint available
  ✓ Client schema generated
  ✓ OpenAPI docs generated

📚 Igniter Studio: http://localhost:3000/api/v1/studio
📖 OpenAPI Docs: http://localhost:3000/api/v1/docs

Ready in 1.2s
```

## Testing Your API

Open your browser and navigate to:

**[http://localhost:3000](http://localhost:3000)** - Your Next.js homepage
**[http://localhost:3000/api/v1/studio](http://localhost:3000/api/v1/studio)** - Igniter Studio (API dashboard)

### Using Igniter Studio

Igniter Studio is an **interactive API playground** that lets you:

* 📋 See all your endpoints
* 🧪 Test API calls directly in the browser
* 📝 View request/response schemas
* 🔍 Inspect the generated TypeScript types

Try calling the example endpoint:

1. Click on **"example"** in the sidebar
2. Click on **"GET /hello"**
3. Click **"Execute"**

You should see a response:

```json
{
  "message": "Hello from example!"
}
```

🎉 **Congratulations!** Your Igniter.js application is running!

<Quiz
  question="What is Igniter Studio used for?"
  options={[
  { label: "A code editor for TypeScript", value: "editor" },
  { label: "An interactive API dashboard for testing endpoints without Postman", value: "dashboard", isCorrect: true },
  { label: "A database management tool", value: "database" },
  { label: "A deployment platform", value: "deploy" }
]}
  explanation="Igniter Studio is an interactive API playground that comes with every Igniter.js project. It lets you explore and test your API endpoints directly in your browser, eliminating the need for tools like Postman or cURL during development."
/>

## Understanding the CLI Commands

Now that your project is running, let's learn about the other powerful CLI commands you'll use throughout development:

### `igniter dev`

```bash
npx igniter dev
```

Starts the development server with:

* 🔥 **Hot-reload** for Igniter.js changes
* 🚀 **Framework server** (Next.js in our case)
* 🎯 **Interactive dashboard** with live API explorer
* 📖 **Auto-generated OpenAPI docs**

<Callout type="info" title="Pro Tip">
  The `dev` command is smart! It automatically detects your framework (Next.js) and runs the appropriate commands. You can also customize it with flags:

  ```bash
  npx igniter dev --port 4000        # Custom port
  npx igniter dev --no-interactive   # Disable interactive mode
  ```
</Callout>

### `igniter generate schema`

```bash
npx igniter generate schema
```

Generates the **TypeScript client** from your Igniter.js router. This runs automatically during `dev`, but you can also run it manually for:

* CI/CD pipelines
* Pre-commit hooks
* Manual type generation

### `igniter generate docs`

```bash
npx igniter generate docs
```

Generates **OpenAPI specification** and optionally a **Scalar UI** for your API documentation.

```bash
npx igniter generate docs --ui   # Generate interactive HTML docs
```

### `igniter generate feature`

```bash
npx igniter generate feature users --schema prisma:User
```

This is where the magic happens! This command:

1. Reads your Prisma schema
2. Generates a complete CRUD controller
3. Creates type-safe queries and mutations
4. Sets up proper file structure

We'll use this extensively in Chapter 4!

## Project Structure Deep Dive

Let's understand how your project is organized:

### Frontend Layer (`src/app/`)

```
src/app/
├── layout.tsx          # Root layout, providers
├── page.tsx            # Homepage
└── api/
    └── [[...igniter]]/ # Igniter.js catch-all route
        └── route.ts
```

This is your **Next.js App Router** structure. The `[[...igniter]]` route is special - it catches all API requests and forwards them to Igniter.js.

### Backend Layer (`src/features/`)

```
src/features/
└── example/
    └── controllers/
        └── example.controller.ts
```

This is your **Igniter.js API**. Each feature is self-contained with its controllers, procedures, and business logic. This **feature-based architecture** keeps your code organized as your app grows.

### Configuration (`src/igniter.*.ts`)

```
src/
├── igniter.ts          # Main Igniter instance
├── igniter.context.ts  # Application context & DI
├── igniter.router.ts   # API router
└── igniter.client.ts   # Auto-generated client
```

These files work together to create your API:

* **`igniter.ts`**: Configures features and adapters
* **`igniter.context.ts`**: Defines what's available globally (DB, logger, etc.)
* **`igniter.router.ts`**: Registers all your controllers
* **`igniter.client.ts`**: Auto-generated type-safe client for the frontend

### Services (`src/services/`)

```
src/services/
├── logger.ts       # Structured logging
└── telemetry.ts    # OpenTelemetry setup
```

These are your **infrastructure services** - things like logging, caching, job processing, etc.

## Next Steps

Your development environment is ready! You've:

* ✅ Created a new Igniter.js project with the CLI
* ✅ Configured your project with the right features
* ✅ Started your development server
* ✅ Tested your first API endpoint
* ✅ Learned about the CLI commands

In the next chapter, we'll design our database schema and set up Prisma to manage our data.

<ChapterNav
  current={{
  number: 1,
  title: "Creating Your Project"
}}
  next={{
  number: 2,
  title: "Designing Your Database",
  description: "Create your database schema with Prisma and set up your data models",
  href: "/learn/02-designing-your-database"
}}
/>


---

# 02: Setup Database

> Design and create your database schema with Prisma
URL: https://igniterjs.com/learn/course/02-designing-your-database

import { ChapterObjectives } from '@/components/learn/chapter-objectives'
import { ChapterNav } from '@/components/learn/chapter-nav'
import { Quiz } from '@/components/learn/quiz'

<ChapterObjectives
  objectives={[
  { text: 'Understand the data model for Shortify' },
  { text: 'Create your Prisma schema' },
  { text: 'Run your first migration' },
  { text: 'Explore your database with Prisma Studio' }
]}
/>

Now that your project is set up, let's design the database. For Shortify, we need to store three main types of information: users, shortened links, and clicks.

## The Data Model

Before writing any code, it's crucial to understand what data our application needs to store and how different pieces of data relate to each other. This upfront planning prevents costly refactoring later.

Our SaaS needs three core models that work together to provide the link shortening functionality:

```prisma
// Users who create and manage links
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  password  String
  name      String?
  createdAt DateTime @default(now())
  links     Link[]
}

// Shortened links created by users
model Link {
  id        String   @id @default(cuid())
  shortCode String   @unique
  url       String
  userId    String
  createdAt DateTime @default(now())
  user      User     @relation(fields: [userId], references: [id])
  clicks    Click[]
}

// Click events tracked for analytics
model Click {
  id        String   @id @default(cuid())
  linkId    String
  createdAt DateTime @default(now())
  link      Link     @relation(fields: [linkId], references: [id])
}
```

### Understanding the Design

Let's break down why we designed the schema this way:

* **User Model**: Stores the essential authentication information. The `email` field is marked as `@unique` to prevent duplicate accounts. The `password` field will store a hashed version (never plain text!). The `links` field creates a one-to-many relationship—one user can have many links.

* **Link Model**: This is the heart of our application. The `shortCode` is what appears in the short URL (e.g., `short.ly/github`), and it must be unique. The `url` is the original long URL we're shortening. The `userId` creates the relationship back to the user who owns this link.

* **Click Model**: Keeps it simple for analytics. Each time someone clicks a link, we create a new `Click` record. This gives us basic analytics like total clicks and click timestamps without the complexity of geolocation or device tracking.

## Creating the Schema

Prisma uses a declarative schema language that's both human-readable and type-safe. When you ran `igniter init`, it created a basic `prisma/schema.prisma` file. Let's build upon it.

Open the file `prisma/schema.prisma`. You'll see the foundational configuration:

```prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
```

The `generator` section tells Prisma to generate a TypeScript client, and the `datasource` section configures the PostgreSQL connection using an environment variable for security.

Now, add the three models we designed above to this file:

```prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  password  String
  name      String?
  createdAt DateTime @default(now())
  links     Link[]
}

model Link {
  id        String   @id @default(cuid())
  shortCode String   @unique
  url       String
  userId    String
  createdAt DateTime @default(now())
  user      User     @relation(fields: [userId], references: [id])
  clicks    Click[]
}

model Click {
  id        String   @id @default(cuid())
  linkId    String
  createdAt DateTime @default(now())
  link      Link     @relation(fields: [linkId], references: [id])
}
```

## Setting Up the Database

Before we can apply this schema, we need to ensure PostgreSQL is running. If you selected Docker during setup, start it with:

```bash
docker-compose up -d
```

This starts PostgreSQL in the background. The `-d` flag means "detached mode"—it runs without blocking your terminal.

Now, push the schema to your database:

```bash
npx prisma db push
```

This single command does three powerful things:

1. **Reads** your `schema.prisma` file
2. **Creates** all the tables in PostgreSQL with the correct structure
3. **Generates** the Prisma Client with full TypeScript types

You should see output confirming that your database is now synchronized with your schema.

<Callout type="info">
  **Why `db push` instead of `migrate`?**\
  During development, `db push` is faster and more flexible—it applies changes directly without creating migration files. When you're ready for production, you'll use `prisma migrate` to create versioned migration files that can be safely applied to production databases.
</Callout>

## Exploring with Prisma Studio

Prisma includes a powerful visual database browser that makes it incredibly easy to inspect and manipulate your data during development.

Launch it with:

```bash
npx prisma studio
```

This opens a web interface at `http://localhost:5555` where you can:

* **View all tables** and their data in a clean UI
* **Create records** manually without writing SQL
* **Edit and delete** data with a few clicks
* **Test relationships** by navigating between related records

<Callout type="success">
  **Pro Tip**: Keep Prisma Studio open in a browser tab while you develop. It's invaluable for quickly checking if your API endpoints are creating data correctly!
</Callout>

## Adding Seed Data

Starting with an empty database makes testing difficult. Let's create a seed script that populates the database with sample data.

Create a new file at `prisma/seed.ts`:

```typescript
import { PrismaClient } from '@prisma/client'
import bcrypt from 'bcryptjs'

const prisma = new PrismaClient()

async function main() {
  // Clean the database
  await prisma.click.deleteMany()
  await prisma.link.deleteMany()
  await prisma.user.deleteMany()

  // Create a test user
  const user = await prisma.user.create({
    data: {
      email: 'test@example.com',
      password: await bcrypt.hash('password123', 10),
      name: 'Test User',
    },
  })

  // Create sample links
  await prisma.link.createMany({
    data: [
      {
        shortCode: 'github',
        url: 'https://github.com',
        userId: user.id,
      },
      {
        shortCode: 'igniter',
        url: 'https://igniterjs.com',
        userId: user.id,
      },
    ],
  })

  console.log('✅ Database seeded successfully!')
}

main()
  .catch((e) => {
    console.error(e)
    process.exit(1)
  })
  .finally(async () => {
    await prisma.$disconnect()
  })
```

This seed script is straightforward but powerful. It clears existing data (useful for development resets), creates a test user with a securely hashed password, and adds a couple of sample links.

Now configure the seed script in your `package.json`:

```json
{
  "prisma": {
    "seed": "tsx prisma/seed.ts"
  }
}
```

Install the required dependencies:

```bash
npm install bcryptjs
npm install -D @types/bcryptjs tsx
```

Finally, run the seed:

```bash
npx prisma db seed
```

Open Prisma Studio again, and you'll see your test data! You now have a user you can log in with and some links to work with.

## Quiz

<Quiz
  question="Why do we use @unique on the shortCode field?"
  options={[
  { label: 'To improve database performance', value: 'performance' },
  { label: 'To ensure each link has a different code', value: 'unique', isCorrect: true },
  { label: 'To create an index in the database', value: 'index' },
  { label: 'It is required by Prisma', value: 'required' }
]}
  explanation="The @unique constraint ensures no two links share the same shortCode. Imagine the chaos if multiple links had the code 'promo'—users would never know which URL they'd get!"
/>

<Quiz
  question="Which command should you use during development to apply schema changes?"
  options={[
  { label: 'prisma migrate dev', value: 'migrate' },
  { label: 'prisma db push', value: 'push', isCorrect: true },
  { label: 'prisma generate', value: 'generate' },
  { label: 'prisma studio', value: 'studio' }
]}
  explanation="During development, `prisma db push` is faster and more practical. It applies changes directly to the database without creating migration files."
/>

<ChapterNav
  current={{ number: 2, title: 'Designing Your Database' }}
  next={{
  number: 3,
  title: 'Your First Feature',
  description: 'Generate a complete CRUD feature using the Igniter.js CLI and understand how controllers, services, and procedures work together.',
  href: '/learn/03-first-feature'
}}
/>


---

# 03: Your First Feature

> Generate and understand your first Igniter.js feature
URL: https://igniterjs.com/learn/course/03-first-feature

import { ChapterObjectives } from '@/components/learn/chapter-objectives'
import { ChapterNav } from '@/components/learn/chapter-nav'
import { Quiz } from '@/components/learn/quiz'

<ChapterObjectives
  objectives={[
  { text: 'Use the CLI to generate a feature' },
  { text: 'Understand the feature structure' },
  { text: 'Learn how controllers handle HTTP requests' },
  { text: 'Understand services and business logic encapsulation' },
  { text: 'Test your feature in Igniter Studio' }
]}
/>

Now that we have our database ready, let's create our first feature using the powerful Igniter.js CLI generator.

## Generating the Feature

The Igniter.js CLI has a powerful command that generates a complete feature structure based on your Prisma schema. This saves you from writing boilerplate code and ensures consistency across your application.

Run this command:

```bash
igniter generate feature link --schema prisma:Link
```

This single command does a lot of heavy lifting:

1. **Reads** the `Link` model from your `schema.prisma`
2. **Creates** the entire folder structure
3. **Generates** controllers with CRUD endpoints
4. **Generates** services for database operations
5. **Configures** end-to-end TypeScript types

<Callout type="info">
  **What is a Feature?**\
  In Igniter.js, a "feature" is a self-contained module that groups all logic related to a specific entity or business domain. It includes controllers (HTTP endpoints), services (business logic and database access), procedures (middleware), and interfaces (types, schemas, and constants).
</Callout>

## Understanding the Generated Structure

After running the command, you'll see this structure in `src/features/link/`:

```
src/features/link/
├── controllers/
│   └── link.controller.ts    # HTTP endpoints (GET, POST, PUT, DELETE)
├── services/
│   └── link.service.ts       # Business logic and database operations
├── procedures/
│   └── link.procedure.ts     # Service injection into context
└── link.interfaces.ts        # Types, Zod schemas, and constants
```

Each file has a specific responsibility. Let's explore them one by one.

## The Controller: Handling HTTP Requests

Controllers are the entry point for HTTP requests. They handle request validation, call business logic, and format responses. Open `src/features/link/controllers/link.controller.ts`:

```typescript
import { igniter } from "@/igniter";
import { z } from "zod";
import { linkProcedure } from "../procedures/link.procedure";
import { CreateLinkBodySchema, UpdateLinkBodySchema } from "../link.interfaces";

export const linkController = igniter.controller({
  name: "link",
  path: "/link",
  actions: {
    // GET /link - List all links
    list: igniter.action({
      method: "GET",
      path: "/",
      use: [linkProcedure],
      handler: async ({ context, response }) => {
        const links = await context.link.service.link.findMany();
        return response.success(links);
      },
    }),

    // GET /link/:id - Get a specific link
    get: igniter.action({
      method: "GET",
      path: "/:id" as const,
      use: [linkProcedure],
      handler: async ({ context, response, request }) => {
        const link = await context.link.service.link.findUnique(
          request.params.id
        );
        
        if (!link) {
          return response.notFound("Link not found");
        }

        return response.success(link);
      },
    }),

    // POST /link - Create a new link
    create: igniter.action({
      method: "POST",
      path: "/",
      body: CreateLinkBodySchema,
      use: [linkProcedure],
      handler: async ({ context, response, request }) => {
        const link = await context.link.service.link.create(request.body);
        return response.created(link);
      },
    }),

    // PUT /link/:id - Update a link
    update: igniter.action({
      method: "PUT",
      path: "/:id" as const,
      body: UpdateLinkBodySchema,
      use: [linkProcedure],
      handler: async ({ context, response, request }) => {
        const link = await context.link.service.link.update(
          request.params.id,
          request.body
        );

        if (!link) {
          return response.notFound("Link not found");
        }

        return response.success(link);
      },
    }),

    // DELETE /link/:id - Delete a link
    delete: igniter.action({
      method: "DELETE",
      path: "/:id" as const,
      use: [linkProcedure],
      handler: async ({ context, response, request }) => {
        await context.link.service.link.delete(request.params.id);
        return response.noContent();
      },
    }),
  },
});
```

### Key Concepts in Controllers

**1. Controller Configuration**: The controller is configured with a `name` (for documentation) and a `path` (the base URL path for all actions).

**2. Actions**: Each action is an HTTP endpoint. The `method` defines the HTTP verb (GET, POST, etc.), the `path` is the URL pattern, and `use` specifies the procedures (middleware) to run before the handler. Notice the `as const` on paths with parameters—this enables TypeScript to infer the correct types for `request.params`.

**3. Request Validation**: The `body` property on `create` and `update` actions automatically validates incoming data using Zod schemas. If validation fails, the request is rejected with a clear error message.

**4. Context Usage**: The handler accesses the service through `context.link.service.link`. This dependency was injected by the `linkProcedure`.

**5. Response Methods**: Igniter.js provides semantic response methods like `response.success()`, `response.created()`, `response.notFound()`, and `response.noContent()`. These ensure correct HTTP status codes and consistent response formats.

## The Service: Encapsulating Business Logic

Services encapsulate all database operations and business logic for a feature. This keeps controllers thin and focused, while making the business logic reusable and testable.

Open `src/features/link/services/link.service.ts`:

```typescript
import { PrismaClient, Link } from "@prisma/client";
import { CreateLinkBody, UpdateLinkBody } from "../link.interfaces";

/**
 * Service responsible for Link entity business logic and data access
 */
export class LinkService {
  constructor(private prisma: PrismaClient) {}

  /**
   * Find all links with related user data
   */
  async findMany() {
    return this.prisma.link.findMany({
      include: {
        user: {
          select: {
            id: true,
            name: true,
            email: true,
          },
        },
      },
    });
  }

  /**
   * Find a single link by ID with full relations
   */
  async findUnique(id: string) {
    return this.prisma.link.findUnique({
      where: { id },
      include: {
        user: true,
        clicks: true,
      },
    });
  }

  /**
   * Create a new link
   */
  async create(data: CreateLinkBody) {
    return this.prisma.link.create({
      data,
    });
  }

  /**
   * Update an existing link
   */
  async update(id: string, data: UpdateLinkBody) {
    return this.prisma.link.update({
      where: { id },
      data,
    });
  }

  /**
   * Delete a link
   */
  async delete(id: string) {
    return this.prisma.link.delete({
      where: { id },
    });
  }
}
```

### Why Services Matter

**Separation of Concerns**: Controllers handle HTTP. Services handle business logic. This separation makes code easier to test and maintain.

**Reusability**: Service methods can be called from multiple controllers, background jobs, or even other services.

**Business Logic**: Services can include validation rules, calculations, and complex queries beyond simple CRUD operations.

**Type Safety**: The service class is fully typed, providing autocomplete and compile-time error checking.

## The Procedure: Injecting Dependencies

Procedures in Igniter.js are middleware that extend the request context. They're perfect for injecting services, validating authentication, or adding any shared functionality.

Open `src/features/link/procedures/link.procedure.ts`:

```typescript
import { igniter } from "@/igniter";
import { LinkService } from "../services/link.service";

/**
 * Procedure that injects LinkService into the request context
 */
export const linkProcedure = igniter.procedure({
  name: "linkProcedure",
  handler: async ({ context }) => {
    return {
      link: {
        service: {
          link: new LinkService(context.database),
        },
      },
    };
  },
});
```

### Understanding Procedures

**Context Extension**: The procedure returns an object that gets merged into the request context. This makes the service available to all downstream handlers.

**Type Safety**: TypeScript automatically infers what's available in `context.link.service.link` based on the returned object.

**Dependency Injection**: By instantiating the service here, we keep controllers clean and make it easy to swap implementations for testing.

**Composition**: Multiple procedures can be chained in the `use` array at the action level. Each procedure runs in order, extending the context with its returned values. This builds up the context step by step before the handler executes.

## The Interfaces: Centralizing Types

All types, Zod schemas, and constants for a feature live in one place. Open `src/features/link/link.interfaces.ts`:

```typescript
import { z } from "zod";

/**
 * Schema for creating a new link
 */
export const CreateLinkBodySchema = z.object({
  shortCode: z.string().min(3, "Short code must be at least 3 characters"),
  url: z.string().url("Must be a valid URL"),
  userId: z.string(),
});

/**
 * Schema for updating a link
 */
export const UpdateLinkBodySchema = z.object({
  shortCode: z.string().min(3, "Short code must be at least 3 characters").optional(),
  url: z.string().url("Must be a valid URL").optional(),
});

/**
 * Type for creating a new link
 */
export type CreateLinkBody = z.infer<typeof CreateLinkBodySchema>;

/**
 * Type for updating a link
 */
export type UpdateLinkBody = z.infer<typeof UpdateLinkBodySchema>;
```

Having all schemas in one file makes them easy to find, update, and reuse.

## Testing with Igniter Studio

Now for the magic. Instead of using `npm run dev`, use the Igniter.js CLI:

```bash
igniter dev
```

This command is more than just a dev server. It:

1. **Starts** your Next.js application
2. **Watches** for file changes
3. **Auto-generates** the TypeScript client when controllers change
4. **Auto-generates** API documentation
5. **Provides** hot module reload

<Callout type="success">
  **Why use `igniter dev`?**\
  The `igniter dev` command monitors your controllers and automatically regenerates the TypeScript client and documentation whenever you make changes. This keeps your frontend and backend perfectly synchronized with zero manual work!
</Callout>

Once running, navigate to `http://localhost:3000/api/igniter/studio`. You'll see:

* **All your endpoints** listed and organized
* **Interactive forms** to test each endpoint
* **Real-time Zod validation** as you type
* **Formatted responses** with syntax highlighting
* **Automatic TypeScript types** generated from your schemas

Try creating a link:

1. Click on `POST /link` in the studio
2. Fill in the test form:
   ```json
   {
     "shortCode": "test",
     "url": "https://example.com",
     "userId": "<id-from-seed-data>"
   }
   ```
3. Click "Send"

You should see a `201 Created` response with your new link!

## Making API Requests

You can also test with `curl` or any HTTP client:

```bash
curl -X POST http://localhost:3000/api/link \
  -H "Content-Type: application/json" \
  -d '{
    "shortCode": "docs",
    "url": "https://igniterjs.com/docs",
    "userId": "your-user-id-here"
  }'
```

## Quiz

<Quiz
  question="What does the command `igniter generate feature` NOT create automatically?"
  options={[
  { label: 'Controllers with CRUD endpoints', value: 'controllers' },
  { label: 'Services with database methods', value: 'services' },
  { label: 'Automated test files', value: 'tests', isCorrect: true },
  { label: 'Zod validation schemas', value: 'schemas' }
]}
  explanation="The generator creates controllers, services, and schemas, but you should write tests yourself. We'll cover testing in future chapters!"
/>

<Quiz
  question="Why use `igniter dev` instead of `npm run dev`?"
  options={[
  { label: 'It is faster to start', value: 'faster' },
  { label: 'It auto-generates client and docs', value: 'autogen', isCorrect: true },
  { label: 'It has prettier terminal colors', value: 'colors' },
  { label: 'It uses less memory', value: 'memory' }
]}
  explanation="The `igniter dev` command watches for changes and automatically regenerates the TypeScript client and documentation, keeping everything synchronized!"
/>

<ChapterNav
  current={{ number: 3, title: 'Your First Feature' }}
  next={{
  number: 4,
  title: 'Authentication',
  description: 'Build a complete authentication system from scratch using JWT, bcrypt, and Igniter.js procedures to protect your routes.',
  href: '/learn/04-authentication'
}}
/>


---

# 04: Authentication

> Build a complete authentication system from scratch
URL: https://igniterjs.com/learn/course/04-authentication

import { ChapterObjectives } from '@/components/learn/chapter-objectives'
import { ChapterNav } from '@/components/learn/chapter-nav'
import { Quiz } from '@/components/learn/quiz'

<ChapterObjectives
  objectives={[
  { text: 'Create auth feature with sign up and sign in' },
  { text: 'Implement password hashing with bcrypt' },
  { text: 'Generate and validate JWT tokens' },
  { text: 'Create an auth procedure to protect routes' },
  { text: 'Use context extension for user sessions' }
]}
/>

Let's build a complete authentication system using only Igniter.js patterns, without complex external dependencies. We'll follow the established framework conventions for maximum type safety and developer experience.

## Creating the Auth Feature

First, let's generate the basic structure:

```bash
igniter generate feature auth --schema prisma:User
```

We'll heavily customize this feature because authentication has specific requirements around security and session management.

## Defining Interfaces and Constants

Authentication requires several constants and schemas. These should be centralized in the interfaces file for easy maintenance and reuse.

Open `src/features/auth/auth.interfaces.ts` and add:

```typescript
import { z } from "zod";

/**
 * Number of salt rounds for bcrypt password hashing
 * Higher numbers = more secure but slower
 */
export const SALT_ROUNDS = 10;

/**
 * JWT secret key from environment variables
 * MUST be set in production to a strong random string
 */
export const JWT_SECRET = process.env.JWT_SECRET || "your-secret-key-change-in-production";

/**
 * JWT token expiration time (7 days)
 * Adjust based on your security requirements
 */
export const JWT_EXPIRES_IN = "7d";

/**
 * Request body schema for user sign up
 * Validates email format and password strength
 */
export const SignUpBodySchema = z.object({
  email: z.string().email("Invalid email format"),
  password: z.string().min(8, "Password must be at least 8 characters"),
  name: z.string().optional(),
});

/**
 * Request body schema for user sign in
 * Simpler validation since we're just checking credentials
 */
export const SignInBodySchema = z.object({
  email: z.string().email("Invalid email format"),
  password: z.string().min(1, "Password is required"),
});

/**
 * Type for sign up request body
 * Inferred from Zod schema for type safety
 */
export type SignUpBody = z.infer<typeof SignUpBodySchema>;

/**
 * Type for sign in request body
 * Inferred from Zod schema for type safety
 */
export type SignInBody = z.infer<typeof SignInBodySchema>;

/**
 * JWT payload structure
 * Contains only public, non-sensitive user data
 */
export type JwtPayload = {
  userId: string;
  email: string;
};
```

These constants and schemas form the foundation of our authentication system. Notice how we use Zod to validate inputs and TypeScript to ensure type safety throughout.

## Creating Global Services

Authentication uses two core services: one for password hashing and one for JWT operations. These are global utilities used across multiple features, so they should be injected at the application level.

Create `src/services/password.service.ts`:

```typescript
import bcrypt from "bcryptjs";

/**
 * Service responsible for password hashing and verification
 * Uses bcrypt for secure one-way hashing
 */
export class PasswordService {
  /**
   * Hash a plain text password
   * @param password - The plain text password to hash
   * @param saltRounds - Number of salt rounds (higher = more secure but slower)
   * @returns Promise resolving to the hashed password
   */
  async hash(password: string, saltRounds: number = 10): Promise<string> {
    return bcrypt.hash(password, saltRounds);
  }

  /**
   * Compare a plain text password with a hash
   * @param password - The plain text password to check
   * @param hash - The hashed password to compare against
   * @returns Promise resolving to true if passwords match
   */
  async compare(password: string, hash: string): Promise<boolean> {
    return bcrypt.compare(password, hash);
  }
}
```

Now create `src/services/jwt.service.ts`:

```typescript
import jwt from "jsonwebtoken";

/**
 * Service responsible for JWT token generation and verification
 * Handles encoding user data into secure tokens
 */
export class JwtService {
  /**
   * Generate a JWT token with the given payload
   * @param payload - Data to encode in the token
   * @param secret - Secret key for signing
   * @param expiresIn - Token expiration time (e.g., "7d", "24h")
   * @returns Signed JWT token string
   */
  sign<T extends object>(
    payload: T,
    secret: string,
    expiresIn: string = "7d"
  ): string {
    return jwt.sign(payload, secret, { expiresIn });
  }

  /**
   * Verify and decode a JWT token
   * @param token - The JWT token to verify
   * @param secret - Secret key used for signing
   * @returns Decoded payload if valid, null if invalid/expired
   */
  verify<T extends object>(token: string, secret: string): T | null {
    try {
      return jwt.verify(token, secret) as T;
    } catch {
      // Token is invalid, expired, or malformed
      return null;
    }
  }
}
```

### Injecting Services Globally

These services need to be available application-wide. Open `src/igniter.context.ts` and inject them:

```typescript
import { database } from "@/services/database";
import { PasswordService } from "@/services/password.service";
import { JwtService } from "@/services/jwt.service";

export const createIgniterAppContext = () => {
  return {
    database,
    services: {
      password: new PasswordService(),
      jwt: new JwtService(),
    },
  };
};

export type IgniterAppContext = ReturnType<typeof createIgniterAppContext>;
```

By placing these in the global context, they're available to any controller or procedure without needing to instantiate them repeatedly.

## Creating the Auth Service

Now let's create the service for user data access. Since this service will be used globally (not just in auth controllers), we'll inject it into the global context as well.

Create `src/services/auth.service.ts`:

```typescript
import { PrismaClient, User } from "@prisma/client";

/**
 * Service responsible for user data access and management
 * Handles database operations for the User entity
 */
export class AuthService {
  constructor(private prisma: PrismaClient) {}

  /**
   * Find a user by email address
   * Used during sign in to locate the account
   */
  async findByEmail(email: string): Promise<User | null> {
    return this.prisma.user.findUnique({
      where: { email },
    });
  }

  /**
   * Find a user by ID
   * Used to fetch user data after JWT validation
   * Excludes password for security
   */
  async findById(id: string): Promise<Omit<User, 'password'> | null> {
    return this.prisma.user.findUnique({
      where: { id },
      select: {
        id: true,
        email: true,
        name: true,
        createdAt: true,
        // Note: password is intentionally excluded
      },
    });
  }

  /**
   * Create a new user account
   * Password should already be hashed before calling this
   */
  async create(data: {
    email: string;
    password: string;
    name?: string;
  }): Promise<User> {
    return this.prisma.user.create({
      data,
    });
  }
}
```

Now inject it into the global context. Open `src/igniter.context.ts` again and add the `AuthService`:

```typescript
import { database } from "@/services/database";
import { PasswordService } from "@/services/password.service";
import { JwtService } from "@/services/jwt.service";
import { AuthService } from "@/services/auth.service";

export const createIgniterAppContext = () => {
  return {
    database,
    services: {
      password: new PasswordService(),
      jwt: new JwtService(),
      auth: new AuthService(database),
    },
  };
};

export type IgniterAppContext = ReturnType<typeof createIgniterAppContext>;
```

The `AuthService` is now available globally via `context.services.auth`, making it easy to use across all controllers and procedures.

## Creating the Auth Controller

Now let's build the controller with sign up, sign in, and session endpoints. We'll also set JWT tokens as HTTP-only cookies for automatic authentication.

Create `src/features/auth/controllers/auth.controller.ts`:

```typescript
import { igniter } from "@/igniter";
import { z } from "zod";
import {
  SignUpBodySchema,
  SignInBodySchema,
  SALT_ROUNDS,
  JWT_SECRET,
  JWT_EXPIRES_IN,
  JwtPayload,
} from "../auth.interfaces";

export const authController = igniter.controller({
  name: "auth",
  path: "/auth",
  actions: {
    /**
     * Sign up a new user account
     */
    signUp: igniter.action({
      method: "POST",
      path: "/signup",
      body: SignUpBodySchema,
      handler: async ({ context, response, request }) => {
        const { email, password, name } = request.body;

        // Business Rule: Check if user already exists
        const existingUser = await context.services.auth.findByEmail(email);

        if (existingUser) {
          return response.badRequest("Email already registered");
        }

        // Business Rule: Hash password before storing
        // Never store plain text passwords!
        const hashedPassword = await context.services.password.hash(
          password,
          SALT_ROUNDS
        );

        // Business Rule: Create user with hashed password
        const user = await context.services.auth.create({
          email,
          password: hashedPassword,
          name,
        });

        // Business Rule: Generate JWT token for immediate login
        // This provides a seamless experience after signup
        const token = context.services.jwt.sign<JwtPayload>(
          {
            userId: user.id,
            email: user.email,
          },
          JWT_SECRET,
          JWT_EXPIRES_IN
        );

        // Business Rule: Set token as HTTP-only cookie for automatic auth
        // This means the frontend doesn't need to manually handle tokens
        return response
          .setCookie('auth-token', token, {
            httpOnly: true,
            secure: process.env.NODE_ENV === 'production',
            sameSite: 'lax',
            maxAge: 60 * 60 * 24 * 7, // 7 days in seconds
            path: '/',
          })
          .created({
            user: {
              id: user.id,
              email: user.email,
              name: user.name,
            },
            token, // Still return token for manual handling if needed
          });
      },
    }),

    /**
     * Sign in an existing user
     */
    signIn: igniter.action({
      method: "POST",
      path: "/signin",
      body: SignInBodySchema,
      handler: async ({ context, response, request }) => {
        const { email, password } = request.body;

        // Business Rule: Find user by email
        const user = await context.services.auth.findByEmail(email);

        if (!user) {
          // Security: Use generic message to prevent email enumeration
          return response.unauthorized("Invalid credentials");
        }

        // Business Rule: Verify password hash
        const isValidPassword = await context.services.password.compare(
          password,
          user.password
        );

        if (!isValidPassword) {
          return response.unauthorized("Invalid credentials");
        }

        // Business Rule: Generate JWT token
        const token = context.services.jwt.sign<JwtPayload>(
          {
            userId: user.id,
            email: user.email,
          },
          JWT_SECRET,
          JWT_EXPIRES_IN
        );

        // Business Rule: Set token as HTTP-only cookie
        return response
          .setCookie('auth-token', token, {
            httpOnly: true,
            secure: process.env.NODE_ENV === 'production',
            sameSite: 'lax',
            maxAge: 60 * 60 * 24 * 7, // 7 days
            path: '/',
          })
          .success({
            user: {
              id: user.id,
              email: user.email,
              name: user.name,
            },
            token, // Also return in body for flexibility
          });
      },
    }),

    /**
     * Get current session (requires authentication)
     */
    getSession: igniter.action({
      method: "GET",
      path: "/session",
      handler: async ({ context, response, request }) => {
        // Business Rule: Try cookie first, then fall back to Authorization header
        const tokenFromCookie = request.cookies.get('auth-token');
        const authHeader = request.headers.get("Authorization");
        const tokenFromHeader = authHeader?.startsWith("Bearer ") 
          ? authHeader.substring(7) 
          : null;

        const token = tokenFromCookie || tokenFromHeader;
        
        if (!token) {
          return response.unauthorized("No token provided");
        }

        // Business Rule: Verify and decode token
        const payload = context.services.jwt.verify<JwtPayload>(
          token,
          JWT_SECRET
        );

        if (!payload) {
          return response.unauthorized("Invalid or expired token");
        }

        // Business Rule: Fetch current user data
        const user = await context.services.auth.findById(payload.userId);

        if (!user) {
          return response.unauthorized("User not found");
        }

        return response.success({
          user: {
            id: user.id,
            email: user.email,
            name: user.name,
          },
        });
      },
    }),

    /**
     * Sign out - clear the auth cookie
     */
    signOut: igniter.action({
      method: "POST",
      path: "/signout",
      handler: async ({ response }) => {
        // Business Rule: Clear the auth cookie
        return response
          .setCookie('auth-token', '', {
            httpOnly: true,
            secure: process.env.NODE_ENV === 'production',
            sameSite: 'lax',
            maxAge: 0, // Expire immediately
            path: '/',
          })
          .success({ message: 'Signed out successfully' });
      },
    }),
  },
});
```

This controller demonstrates several key authentication patterns:

**Sign Up**: Validates input, checks for existing users, hashes the password, creates the account, generates a JWT token, **and sets it as an HTTP-only cookie**.

**Sign In**: Verifies credentials using bcrypt, generates a JWT token, and **sets it as an HTTP-only cookie** for automatic authentication.

**Get Session**: Validates a JWT token from **cookies first (preferred)**, falls back to Authorization header, and returns the current user data.

**Sign Out**: Clears the auth cookie by setting its maxAge to 0.

### Why HTTP-Only Cookies?

Using HTTP-only cookies for JWT tokens provides several security benefits:

1. **XSS Protection**: JavaScript cannot access HTTP-only cookies, protecting against cross-site scripting attacks
2. **Automatic Inclusion**: Browsers automatically include cookies in requests, so the frontend doesn't need to manually add Authorization headers
3. **Secure Flag**: In production, cookies are marked as `secure`, meaning they only transmit over HTTPS
4. **SameSite Protection**: The `sameSite: 'lax'` setting protects against CSRF attacks

The token is still returned in the response body for flexibility (e.g., for mobile apps or custom authentication flows).

Notice the detailed comments explaining each business rule. This makes the code self-documenting.

## Creating the Auth Procedure

Now let's create a procedure to protect routes. This procedure will validate JWT tokens and inject the authenticated user into the context.

Create `src/features/auth/procedures/auth.procedure.ts`:

```typescript
import { igniter } from "@/igniter";
import { User } from "@prisma/client";
import { JWT_SECRET, JwtPayload } from "../auth.interfaces";

/**
 * Options for configuring the auth procedure
 */
type AuthProcedureOptions = {
  /** If false, allows requests without authentication */
  required?: boolean;
};

/**
 * Procedure that validates JWT and injects user into context
 * Can be configured to make authentication optional or required
 */
export const authProcedure = igniter.procedure<AuthProcedureOptions>({
  name: "authProcedure",
  handler: async (options, { context, request }) => {
    // Business Rule: Try cookie first, then fall back to Authorization header
    const tokenFromCookie = request.cookies.get('auth-token');
    const authHeader = request.headers.get("Authorization");
    const tokenFromHeader = authHeader?.startsWith("Bearer ") 
      ? authHeader.substring(7) 
      : null;

    const token = tokenFromCookie || tokenFromHeader;

    if (!token) {
      // Observation: If auth is required, return error response
      if (options?.required !== false) {
        return context.response.unauthorized("Authentication required");
      }
      // Observation: If auth is optional, return null user
      return {
        auth: {
          session: {
            user: null,
          },
        },
      };
    }

    // Business Rule: Verify JWT token
    const payload = context.services.jwt.verify<JwtPayload>(token, JWT_SECRET);

    if (!payload) {
      if (options?.required !== false) {
        return context.response.unauthorized("Invalid or expired token");
      }
      return {
        auth: {
          session: {
            user: null,
          },
        },
      };
    }

    // Business Rule: Fetch user from database
    const user = await context.services.auth.findById(payload.userId);

    if (!user) {
      if (options?.required !== false) {
        return context.response.unauthorized("User not found");
      }
      return {
        auth: {
          session: {
            user: null,
          },
        },
      };
    }

    // Observation: Inject authenticated user into context
    return {
      auth: {
        session: {
          user,
        },
      },
    };
  },
});
```

### Understanding the Auth Procedure

This procedure is incredibly powerful. Let's break down its key features:

1. **Options Parameter First**: The handler signature is `async (options, { context, request })`. This is the standard pattern for Igniter.js procedures - options come first, then the context object.

2. **Cookie-First Authentication**: Checks `request.cookies.get('auth-token')` first, then falls back to the `Authorization` header. This dual approach provides flexibility while prioritizing the more secure cookie method.

3. **Optional Authentication**: The `required` option (defaults to `true`) allows routes to make authentication optional. When `required: false`, the procedure returns `user: null` instead of an error.

4. **Global Service Usage**: Uses `context.services.jwt` and `context.services.auth` which are injected in the global context. No manual service instantiation needed.

5. **Context Extension**: Returns an object that extends the context with `auth.session.user`, making the authenticated user available to all subsequent handlers in the chain.

6. **Type Inference**: TypeScript automatically infers the extended context type. There's no need for explicit type annotations like `as AuthContext` - the framework handles this for you.

## Protecting Routes

Now we can protect the link controller. Open `src/features/link/controllers/link.controller.ts` and add the `authProcedure`:

```typescript
import { authProcedure } from "@/features/auth/procedures/auth.procedure";
import { linkProcedure } from "../procedures/link.procedure";

export const linkController = igniter.controller({
  name: "link",
  path: "/link",
  actions: {
    create: igniter.action({
      method: "POST",
      path: "/",
      body: CreateLinkBodySchema,
      use: [authProcedure, linkProcedure], // Auth first, then link!
      handler: async ({ context, response, request }) => {
        // Business Rule: Use authenticated user ID
        // TypeScript knows user exists because authProcedure is required by default
        const userId = context.auth.session.user!.id;

        const link = await context.link.service.link.create({
          ...request.body,
          userId, // Ensures link belongs to authenticated user
        });

        return response.created(link);
      },
    }),
    // ... other endpoints
  },
});
```

Now all endpoints in the link controller are protected. Requests without a valid JWT token will be rejected with a 401 error.

## Integrating Auth with the Link Feature

Now that we have authentication working, we need to update the Link feature from Chapter 3 to use the authenticated user's ID. This ensures each link is owned by a specific user.

### Update the Link Interface

First, remove `userId` from the create body schema since it will come from the auth context. Open `src/features/link/link.interfaces.ts`:

```typescript
import { z } from "zod";

export const CreateLinkBodySchema = z.object({
  shortCode: z.string().min(1),
  url: z.string().url(),
  // Remove userId - it comes from auth context now
});

export type CreateLinkBody = z.infer<typeof CreateLinkBodySchema>;
```

### Update the Link Service

The `LinkService` should accept `userId` as a parameter and filter results by user. Open `src/features/link/services/link.service.ts`:

```typescript
import { PrismaClient } from "@prisma/client";
import { CreateLinkBody } from "../link.interfaces";

export class LinkService {
  constructor(private readonly database: PrismaClient) {}

  /**
   * Create a new link for a specific user
   */
  async create(data: CreateLinkBody, userId: string) {
    return this.database.link.create({
      data: {
        ...data,
        userId, // Associate link with user
      },
    });
  }

  /**
   * Find all links for a specific user
   */
  async findMany(userId: string) {
    return this.database.link.findMany({
      where: { userId },
      orderBy: { createdAt: "desc" },
    });
  }

  /**
   * Find a link by ID (ensuring it belongs to the user)
   */
  async findById(id: string, userId: string) {
    return this.database.link.findFirst({
      where: { id, userId },
    });
  }

  // Add more methods as needed (update, delete, etc.)
}
```

### Update the Link Controller

Now update the controller to use the authenticated user ID from context. Open `src/features/link/controllers/link.controller.ts`:

```typescript
import { igniter } from "@/igniter";
import { authProcedure } from "@/features/auth/procedures/auth.procedure";
import { linkProcedure } from "../procedures/link.procedure";
import { CreateLinkBodySchema } from "../link.interfaces";

export const linkController = igniter.controller({
  name: "link",
  path: "/link",
  actions: {
    /**
     * Create a new link (requires authentication)
     */
    create: igniter.action({
      method: "POST",
      path: "/",
      body: CreateLinkBodySchema,
      use: [authProcedure, linkProcedure], // Auth provides user, link provides service
      handler: async ({ context, response, request }) => {
        // Get user ID from auth context (guaranteed to exist because authProcedure is required)
        const userId = context.auth.session.user!.id;

        // Create link with user ID from context, not from request body
        const link = await context.link.service.link.create(
          request.body,
          userId
        );

        return response.created(link);
      },
    }),

    /**
     * List all links for the authenticated user
     */
    list: igniter.action({
      method: "GET",
      path: "/",
      use: [authProcedure, linkProcedure],
      handler: async ({ context, response }) => {
        const userId = context.auth.session.user!.id;
        const links = await context.link.service.link.findMany(userId);

        return response.success(links);
      },
    }),

    /**
     * Get a specific link (only if it belongs to the user)
     */
    getById: igniter.action({
      method: "GET",
      path: "/:id",
      use: [authProcedure, linkProcedure],
      handler: async ({ context, response, request }) => {
        const userId = context.auth.session.user!.id;
        const link = await context.link.service.link.findById(
          request.params.id,
          userId
        );

        if (!link) {
          return response.notFound("Link not found or you don't have access");
        }

        return response.success(link);
      },
    }),
  },
});
```

### Key Security Improvements

By integrating authentication with the Link feature:

1. **No Trust in Client Input**: The `userId` never comes from the request body - it's extracted from the verified JWT token in the auth context.

2. **Automatic Access Control**: Each database query filters by `userId`, ensuring users can only see and modify their own links.

3. **Type Safety**: TypeScript knows that `context.auth.session.user` exists after the `authProcedure` runs.

4. **Clean Separation**: Auth logic is in the `authProcedure`, business logic is in the `LinkService`. The controller just wires them together.

This is the power of Igniter.js procedures - they extend the context with domain-specific data (like the authenticated user), and subsequent procedures and handlers can use that data with full type safety.

## Installing Dependencies

Install the required packages:

```bash
npm install bcryptjs jsonwebtoken
npm install -D @types/bcryptjs @types/jsonwebtoken
```

## Testing the Authentication

Configure the JWT secret in `.env`:

```bash
JWT_SECRET="your-super-secret-jwt-key-change-this-in-production"
```

<Callout type="warn">
  **Security Warning**: In production, use a strong, randomly generated secret. Never commit secrets to version control!
</Callout>

Test the signup endpoint:

```bash
curl -X POST http://localhost:3000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123",
    "name": "John Doe"
  }'
```

You'll receive a JWT token in the response. Copy it and use it to create a link:

```bash
curl -X POST http://localhost:3000/api/links \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "shortCode": "test",
    "url": "https://example.com"
  }'
```

<Callout type="success">
  **Congratulations!** You've built a complete authentication system from scratch using only Igniter.js patterns. No complex external dependencies, complete type safety, and full control over the implementation!
</Callout>

## Quiz

<Quiz
  question="Why do we inject PasswordService and JwtService into igniter.context.ts?"
  options={[
  { label: 'To save memory', value: 'memory' },
  { label: 'They are global services used by multiple features', value: 'global', isCorrect: true },
  { label: 'To improve performance', value: 'performance' },
  { label: 'It is required by Igniter.js', value: 'required' }
]}
  explanation="Global services (like password and JWT) are used by multiple features and should be injected in the global context to be accessible throughout the app."
/>

<Quiz
  question="What does authProcedure do when required is false?"
  options={[
  { label: 'Returns 401 error', value: 'error' },
  { label: 'Returns user: null in context', value: 'null', isCorrect: true },
  { label: 'Ignores the token completely', value: 'ignore' },
  { label: 'Redirects to login', value: 'redirect' }
]}
  explanation="When required is false, the procedure allows access without authentication but returns user: null in the context, enabling conditional logic in handlers."
/>

<ChapterNav
  current={{ number: 4, title: 'Authentication' }}
  next={{
  number: 5,
  title: 'Frontend Setup',
  description: 'Connect your frontend using the auto-generated Igniter.js client with full type safety and built-in React hooks.',
  href: '/learn/05-frontend-setup'
}}
/>


---

# 05: Frontend Setup

> Set up the Next.js frontend with middleware authentication, Igniter.js client, and beautiful authentication forms using Shadcn UI and React Hook Form.
URL: https://igniterjs.com/learn/course/05-frontend-setup

In this chapter, we'll build the complete frontend for Shortify. You'll learn how to protect routes using Next.js middleware, configure the type-safe Igniter.js client, and create beautiful authentication forms with proper validation.

<ChapterObjectives
  objectives={[
{ text: "Configure Next.js 16 proxy.ts for route protection" },
{ text: "Set up the Igniter.js client with end-to-end type safety" },
{ text: "Create authentication forms using Shadcn UI, React Hook Form, and Zod" },
{ text: "Structure the presentation layer following Igniter.js best practices" }
]}
/>

## Creating the Middleware (proxy.ts)

Next.js 16 renamed middleware to `proxy.ts`. This file acts as a gatekeeper, checking authentication before allowing access to protected pages.

The middleware runs at the edge, making it extremely fast. It should only perform lightweight checks—heavy logic belongs in API routes or server components.

Create `src/proxy.ts`:

```typescript
import { NextRequest, NextResponse } from 'next/server';
import { api } from '@/igniter.client';

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  
  // Business Rule: Define application routes
  const pages = {
    signIn: '/auth/login',
    signUp: '/auth/signup',
    protected: '/app',
    publicHome: '/',
  };

  // Business Rule: Allow public access to the landing page
  if (pathname === pages.publicHome) {
    return NextResponse.next();
  }

  // Business Rule: Allow access to auth pages without session check
  if (pathname.startsWith('/auth/')) {
    return NextResponse.next();
  }

  // Business Logic: Check authentication status
  // This is a lightweight call - just validating the session token
  try {
    const session = await api.auth.getSession.query();
    const isAuthenticated = !!session?.data?.user?.id;

    // Business Rule: Redirect authenticated users away from auth pages
    if (isAuthenticated && (pathname === pages.signIn || pathname === pages.signUp)) {
      return NextResponse.redirect(new URL(pages.protected, request.url));
    }

    // Business Rule: Protect app routes - require authentication
    if (pathname.startsWith(pages.protected) && !isAuthenticated) {
      return NextResponse.redirect(new URL(pages.signIn, request.url));
    }
  } catch (error) {
    // Business Rule: On session check error, redirect to login for protected routes
    if (pathname.startsWith(pages.protected)) {
      return NextResponse.redirect(new URL(pages.signIn, request.url));
    }
  }
  
  // Default: Allow the request to proceed
  return NextResponse.next();
}

export const config = {
  // Use Node.js runtime for full compatibility with Igniter.js client
  runtime: 'nodejs',
  
  // Business Rule: Run middleware on all routes except static assets
  matcher: [
    /*
     * Match all request paths except:
     * - api (API routes)
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico, sitemap.xml, robots.txt (metadata files)
     */
    '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};
```

### Understanding the Middleware

**1. Route Definition**: The `pages` object centralizes all route paths, making them easy to update and maintain.

**2. Public Routes**: The landing page (`/`) and authentication pages (`/auth/*`) are accessible without authentication.

**3. Session Check**: We call `api.auth.getSession.query()` to verify authentication. This is fast because it only validates the cookie token—no database queries in the middleware.

**4. Redirect Logic**:

* Authenticated users accessing `/auth/login` → redirect to `/app` (dashboard)
* Unauthenticated users accessing `/app` → redirect to `/auth/login`

**5. Error Handling**: If the session check fails (e.g., invalid token), unauthenticated users are redirected to login.

**6. Matcher Configuration**: The `matcher` prevents the middleware from running on static assets, API routes, and metadata files, improving performance.

<Callout type="info" title="Why Node.js Runtime?">
  We use `runtime: 'nodejs'` instead of `'edge'` because the Igniter.js client requires full Node.js APIs. The Edge runtime has limitations that prevent proper client initialization.
</Callout>

## Configuring the Igniter.js Client

The Igniter.js client provides full type safety from server to frontend. It automatically generates typed hooks for all your controllers, giving you autocomplete, type checking, and runtime validation—all with zero configuration.

Create `src/igniter.client.ts`:

```typescript
import { createIgniterClient } from '@igniter-js/core/client';
import type { AppRouter } from './igniter';

/**
 * Type-safe Igniter.js client for frontend
 * 
 * This client provides:
 * - Full TypeScript inference from your backend router
 * - React hooks (useQuery, useMutation, useRealtime)
 * - Automatic request/response validation
 * - Built-in error handling
 * - Cookie-based authentication support
 */
export const api = createIgniterClient<AppRouter>({
  // Business Rule: Use environment variable for API URL
  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000',
  
  // Business Rule: API routes are under /api/v1
  basePATH: '/api/v1',
  
  // Business Rule: Import router for type inference
  router: () => {
    if (typeof window === 'undefined') {
      // Server-side: Direct function calls (zero HTTP overhead)
      return require('./igniter').router;
    }
    // Client-side: HTTP-based requests with React hooks
    return require('./igniter.schema').RouterSchema;
  },
  
  // Business Rule: Include credentials for cookie-based auth
  credentials: 'include',
});
```

### Understanding the Client Configuration

**1. Type Safety**: The `AppRouter` type is imported from your backend, giving the client complete knowledge of all available endpoints, their parameters, and return types.

**2. Environment-Aware**: Uses `NEXT_PUBLIC_API_URL` in production, falls back to `localhost:3000` in development.

**3. Universal Client**: Works on both server and client:

* **Server**: Direct function calls through the router (React Server Components, API routes)
* **Client**: HTTP requests with React hooks (Client Components)

**4. Cookie Support**: `credentials: 'include'` ensures cookies (including the auth token) are automatically sent with every request.

Now add the client provider to your root layout. Open `src/app/layout.tsx`:

```typescript
import { IgniterProvider } from '@igniter-js/core/client';
import './globals.css';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <IgniterProvider>
          {children}
        </IgniterProvider>
      </body>
    </html>
  );
}
```

The `<IgniterProvider>` wraps your app, providing React Query context for all Igniter.js hooks (`useQuery`, `useMutation`, `useRealtime`).

## Structuring the Presentation Layer

Following Igniter.js best practices, we'll organize the authentication UI into a feature module under `src/features/auth/presentation/components/`. This keeps the auth-related components together and organized.

Create the directory structure:

```bash
mkdir -p src/features/auth/presentation/components
```

<Files>
  <Folder name="src">
    <Folder name="features">
      <Folder name="auth">
        <Folder name="presentation" defaultOpen>
          <Folder name="components">
            <File name="login-form.tsx" />

            <File name="signup-form.tsx" />
          </Folder>
        </Folder>
      </Folder>
    </Folder>
  </Folder>
</Files>

This simple structure keeps all authentication UI components in one place, making them easy to find and maintain.

## Building the Login Form

Now let's create the login form component using Shadcn UI and React Hook Form. We'll keep everything self-contained in the component—the validation schema, the form logic, and the API calls.

First, make sure you have the required Shadcn UI components installed:

```bash
npx shadcn@latest add card input button field
```

Create `src/features/auth/presentation/components/login-form.tsx`:

```typescript
'use client';

import { Controller, useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { useRouter } from 'next/navigation';
import { z } from 'zod';
import { toast } from 'sonner';
import { Button } from '@/components/ui/button';
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';
import {
  Field,
  FieldError,
  FieldGroup,
  FieldLabel,
} from '@/components/ui/field';
import { Input } from '@/components/ui/input';
import Link from 'next/link';
import { api } from '@/igniter.client';

// Validation schema defined inline
const loginSchema = z.object({
  email: z
    .string()
    .min(1, 'Email is required')
    .email('Enter a valid email address'),
  password: z
    .string()
    .min(1, 'Password is required')
    .min(8, 'Password must be at least 8 characters'),
});

type LoginFormData = z.infer<typeof loginSchema>;

export function LoginForm() {
  const router = useRouter();

  // Setup the form with validation
  const form = useForm<LoginFormData>({
    resolver: zodResolver(loginSchema),
    defaultValues: {
      email: '',
      password: '',
    },
  });

  // Setup the mutation for login
  const loginMutation = api.auth.signIn.useMutation({
    onSuccess: (data) => {
      toast.success('Welcome back!', {
        description: `Logged in as ${data.user.email}`,
      });
      router.push('/app');
    },
    onError: (error) => {
      toast.error('Login failed', {
        description: error.message || 'Invalid email or password',
      });
    },
  });

  // Handle form submission
  const onSubmit = async (data: LoginFormData) => {
    await loginMutation.mutate({
      body: {
        email: data.email,
        password: data.password,
      },
    });
  };

  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle className="text-2xl">Login</CardTitle>
        <CardDescription>
          Enter your email and password to access your account
        </CardDescription>
      </CardHeader>
      <CardContent>
        <form onSubmit={form.handleSubmit(onSubmit)}>
          <FieldGroup>
            <Controller
              name="email"
              control={form.control}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid}>
                  <FieldLabel htmlFor="login-email">Email</FieldLabel>
                  <Input
                    {...field}
                    id="login-email"
                    type="email"
                    placeholder="you@example.com"
                    autoComplete="email"
                    aria-invalid={fieldState.invalid}
                  />
                  {fieldState.invalid && (
                    <FieldError errors={[fieldState.error]} />
                  )}
                </Field>
              )}
            />

            <Controller
              name="password"
              control={form.control}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid}>
                  <FieldLabel htmlFor="login-password">Password</FieldLabel>
                  <Input
                    {...field}
                    id="login-password"
                    type="password"
                    placeholder="••••••••"
                    autoComplete="current-password"
                    aria-invalid={fieldState.invalid}
                  />
                  {fieldState.invalid && (
                    <FieldError errors={[fieldState.error]} />
                  )}
                </Field>
              )}
            />

            <Button 
              type="submit" 
              className="w-full" 
              disabled={loginMutation.isLoading}
            >
              {loginMutation.isLoading ? 'Logging in...' : 'Login'}
            </Button>
          </FieldGroup>
        </form>

        <div className="mt-4 text-center text-sm">
          Don't have an account?{' '}
          <Link href="/auth/signup" className="underline underline-offset-4">
            Sign up
          </Link>
        </div>
      </CardContent>
    </Card>
  );
}
```

### Understanding the Login Form

**1. Inline Validation Schema**: The Zod schema is defined directly in the component file. This makes it easy to see what validation rules apply without jumping between files.

**2. React Hook Form Integration**: `useForm` manages form state, validation, and submission. The `zodResolver` connects Zod validation to React Hook Form.

**3. Igniter.js Mutation**: We call `api.auth.signIn.useMutation()` directly in the component. The mutation handles the API call, loading states, and success/error callbacks.

**4. Controller Component**: Wraps each input field, providing access to `field` (for input props) and `fieldState` (for validation errors).

**5. Error Display**: `<FieldError>` automatically shows validation errors below each field when `fieldState.invalid` is true.

**6. Loading State**: The submit button uses `loginMutation.isLoading` to show feedback and prevent duplicate submissions.

**7. Accessibility**: Proper `htmlFor`, `aria-invalid`, and `autoComplete` attributes for screen readers and browsers.

## Building the Signup Form

The signup form follows the same pattern as the login form, with additional fields for name and password confirmation. Everything is self-contained in one file.

Create `src/features/auth/presentation/components/signup-form.tsx`:

```typescript
'use client';

import { Controller, useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { useRouter } from 'next/navigation';
import { z } from 'zod';
import { toast } from 'sonner';
import { Button } from '@/components/ui/button';
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';
import {
  Field,
  FieldError,
  FieldGroup,
  FieldLabel,
} from '@/components/ui/field';
import { Input } from '@/components/ui/input';
import Link from 'next/link';
import { api } from '@/igniter.client';

// Validation schema with password confirmation
const signupSchema = z.object({
  name: z
    .string()
    .min(1, 'Name is required')
    .min(2, 'Name must be at least 2 characters')
    .max(100, 'Name must be less than 100 characters'),
  email: z
    .string()
    .min(1, 'Email is required')
    .email('Enter a valid email address'),
  password: z
    .string()
    .min(1, 'Password is required')
    .min(8, 'Password must be at least 8 characters')
    .regex(
      /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/,
      'Password must contain uppercase, lowercase, and number'
    ),
  confirmPassword: z
    .string()
    .min(1, 'Please confirm your password'),
}).refine((data) => data.password === data.confirmPassword, {
  message: 'Passwords do not match',
  path: ['confirmPassword'],
});

type SignupFormData = z.infer<typeof signupSchema>;

export function SignupForm() {
  const router = useRouter();

  // Setup the form with validation
  const form = useForm<SignupFormData>({
    resolver: zodResolver(signupSchema),
    defaultValues: {
      name: '',
      email: '',
      password: '',
      confirmPassword: '',
    },
  });

  // Setup the mutation for signup
  const signupMutation = api.auth.signUp.useMutation({
    onSuccess: (data) => {
      toast.success('Account created!', {
        description: `Welcome, ${data.user.name}!`,
      });
      router.push('/app');
    },
    onError: (error) => {
      toast.error('Signup failed', {
        description: error.message || 'Could not create account',
      });
    },
  });

  // Handle form submission
  const onSubmit = async (data: SignupFormData) => {
    await signupMutation.mutate({
      body: {
        name: data.name,
        email: data.email,
        password: data.password,
      },
    });
  };

  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle className="text-2xl">Create an account</CardTitle>
        <CardDescription>
          Enter your information to get started with Shortify
        </CardDescription>
      </CardHeader>
      <CardContent>
        <form onSubmit={form.handleSubmit(onSubmit)}>
          <FieldGroup>
            <Controller
              name="name"
              control={form.control}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid}>
                  <FieldLabel htmlFor="signup-name">Full Name</FieldLabel>
                  <Input
                    {...field}
                    id="signup-name"
                    type="text"
                    placeholder="John Doe"
                    autoComplete="name"
                    aria-invalid={fieldState.invalid}
                  />
                  {fieldState.invalid && (
                    <FieldError errors={[fieldState.error]} />
                  )}
                </Field>
              )}
            />

            <Controller
              name="email"
              control={form.control}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid}>
                  <FieldLabel htmlFor="signup-email">Email</FieldLabel>
                  <Input
                    {...field}
                    id="signup-email"
                    type="email"
                    placeholder="you@example.com"
                    autoComplete="email"
                    aria-invalid={fieldState.invalid}
                  />
                  {fieldState.invalid && (
                    <FieldError errors={[fieldState.error]} />
                  )}
                </Field>
              )}
            />

            <Controller
              name="password"
              control={form.control}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid}>
                  <FieldLabel htmlFor="signup-password">Password</FieldLabel>
                  <Input
                    {...field}
                    id="signup-password"
                    type="password"
                    placeholder="••••••••"
                    autoComplete="new-password"
                    aria-invalid={fieldState.invalid}
                  />
                  {fieldState.invalid && (
                    <FieldError errors={[fieldState.error]} />
                  )}
                </Field>
              )}
            />

            <Controller
              name="confirmPassword"
              control={form.control}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid}>
                  <FieldLabel htmlFor="signup-confirm">
                    Confirm Password
                  </FieldLabel>
                  <Input
                    {...field}
                    id="signup-confirm"
                    type="password"
                    placeholder="••••••••"
                    autoComplete="new-password"
                    aria-invalid={fieldState.invalid}
                  />
                  {fieldState.invalid && (
                    <FieldError errors={[fieldState.error]} />
                  )}
                </Field>
              )}
            />

            <Button 
              type="submit" 
              className="w-full" 
              disabled={signupMutation.isLoading}
            >
              {signupMutation.isLoading ? 'Creating account...' : 'Create account'}
            </Button>
          </FieldGroup>
        </form>

        <div className="mt-4 text-center text-sm">
          Already have an account?{' '}
          <Link href="/auth/login" className="underline underline-offset-4">
            Login
          </Link>
        </div>
      </CardContent>
    </Card>
  );
}
```

### Key Differences in the Signup Form

**1. Extended Validation**: The signup schema includes a `name` field and password confirmation with a `.refine()` method to ensure passwords match.

**2. Password Strength**: The password field uses a regex to require uppercase, lowercase, and numbers for better security.

**3. Confirmation Field**: The `confirmPassword` field is validated but not sent to the API—only used for client-side verification.

Both forms follow the same pattern: define the schema inline, setup the form, create the mutation, and handle submission. This makes the code easy to understand and maintain.

## Creating the Auth Pages

Now we'll create the actual pages that use these forms. Next.js 15+ uses the App Router, so we'll create pages in the `src/app/` directory.

Create `src/app/auth/login/page.tsx`:

```typescript
import { LoginForm } from '@/features/auth/presentation/components/login-form';

export const metadata = {
  title: 'Login - Shortify',
  description: 'Log in to your Shortify account',
};

export default function LoginPage() {
  return (
    <div className="flex min-h-screen items-center justify-center px-4">
      <LoginForm />
    </div>
  );
}
```

Create `src/app/auth/signup/page.tsx`:

```typescript
import { SignupForm } from '@/features/auth/presentation/components/signup-form';

export const metadata = {
  title: 'Sign Up - Shortify',
  description: 'Create a new Shortify account',
};

export default function SignupPage() {
  return (
    <div className="flex min-h-screen items-center justify-center px-4">
      <SignupForm />
    </div>
  );
}
```

## Testing the Authentication Flow

Start your development server:

```bash
igniter dev
```

Now test the complete authentication flow:

1. **Navigate to `/auth/signup`** and create an account
   * Fill in name, email, password, and confirmation
   * Click "Create account"
   * You should see a success toast and be redirected to `/app`

2. **Try accessing `/app` without logging in**
   * The middleware should redirect you to `/auth/login`

3. **Log in with your credentials**
   * Enter email and password
   * Click "Login"
   * You should be redirected to `/app`

4. **Try accessing `/auth/login` while logged in**
   * The middleware should redirect you to `/app` (you're already authenticated)

<Callout type="success" title="Authentication Complete!">
  You now have a fully functional authentication system with:

  * Protected routes via middleware
  * Type-safe API calls with the Igniter.js client
  * Beautiful, accessible forms with validation
  * Proper error handling and user feedback
</Callout>

## Key Concepts Review

**1. Middleware (proxy.ts)**: Runs at the edge to protect routes. It should only perform lightweight checks—no database queries or heavy logic.

**2. Igniter.js Client**: Provides end-to-end type safety from backend to frontend. The client automatically generates typed hooks for all your controllers.

**3. Self-Contained Components**: Keep validation schemas, API calls, and UI logic together in each component. This makes the code easier to understand and maintain.

**4. Form Validation**: Use Zod schemas with React Hook Form. The `zodResolver` connects them seamlessly, providing both type safety and runtime validation.

## Quiz

<Quiz
  question="Why do we use runtime: 'nodejs' in the middleware config?"
  options={[
  { label: 'It is faster than edge', value: 'faster' },
  { label: 'Igniter.js client requires full Node.js APIs', value: 'apis', isCorrect: true },
  { label: 'Edge runtime is deprecated', value: 'deprecated' },
  { label: 'It supports more browsers', value: 'browsers' }
]}
  explanation="The Igniter.js client needs full Node.js API compatibility. The Edge runtime has limitations that prevent proper client initialization."
/>

<Quiz
  question="What does the Igniter.js client provide?"
  options={[
  { label: 'Only HTTP requests', value: 'http' },
  { label: 'End-to-end type safety with React hooks', value: 'types', isCorrect: true },
  { label: 'Database access', value: 'database' },
  { label: 'Server rendering', value: 'ssr' }
]}
  explanation="The client provides full TypeScript inference from your backend router, React hooks (useQuery, useMutation, useRealtime), and automatic validation—all with zero configuration."
/>

<ChapterNav
  current={{ number: 5, title: 'Frontend Setup' }}
  next={{
  number: 6,
  title: 'Link Management UI',
  description: 'Build the dashboard UI to create, list, and manage shortened links with full CRUD operations.',
  href: '/learn/06-link-management-ui'
}}
/>


---

# 06: Link Management UI

> Build a professional dashboard with analytics cards, link tables, and CRUD operations using Shadcn UI blocks and the Igniter.js client.
URL: https://igniterjs.com/learn/course/06-link-management-ui

In this chapter, we'll build the complete dashboard for Shortify. You'll create a professional interface with analytics cards, a data table for managing links, and full CRUD operations—all powered by the type-safe Igniter.js client.

<ChapterObjectives
  objectives={[
{ text: "Install and configure Shadcn UI dashboard components" },
{ text: "Create a dashboard layout with sidebar navigation" },
{ text: "Build an analytics overview page with stats cards" },
{ text: "Implement a link management page with data table" },
{ text: "Add CRUD operations using Igniter.js hooks" }
]}
/>

## Installing Dashboard Components

The Shadcn UI dashboard block provides a complete, production-ready layout with sidebar, navigation, and card components. Let's install everything we need:

```bash
npx shadcn@latest add card table button badge dialog sheet sidebar
```

These components will give us:

* **Card** - For analytics statistics
* **Table** - For displaying links in a data table
* **Button** - For actions and navigation
* **Badge** - For status indicators (active/inactive)
* **Dialog** - For create/edit forms
* **Sheet** - For mobile navigation
* **Sidebar** - For app navigation

## Creating the Dashboard Layout

The dashboard layout provides consistent navigation and structure across all protected pages. It uses a sidebar for navigation and a content area for page content.

Create `src/app/app/layout.tsx`:

```typescript
import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';
import { AppSidebar } from '@/features/dashboard/presentation/components/app-sidebar';
import {
  SidebarInset,
  SidebarProvider,
} from '@/components/ui/sidebar';

export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <SidebarProvider>
      <AppSidebar />
      <SidebarInset>
        <main className="flex flex-1 flex-col gap-4 p-4 lg:gap-6 lg:p-6">
          {children}
        </main>
      </SidebarInset>
    </SidebarProvider>
  );
}
```

### Understanding the Layout

**1. SidebarProvider**: Manages sidebar state (open/closed) and provides context to child components.

**2. AppSidebar**: The navigation sidebar with links to different sections of the app.

**3. SidebarInset**: The main content area that adjusts based on sidebar state.

**4. Server Component**: This is a server component, allowing us to perform server-side checks before rendering.

## Building the Sidebar Component

The sidebar provides navigation to different sections of the dashboard. It includes user information, navigation links, and a logout button.

Create `src/features/dashboard/presentation/components/app-sidebar.tsx`:

```typescript
'use client';

import { usePathname } from 'next/navigation';
import Link from 'next/link';
import {
  LayoutDashboard,
  Link as LinkIcon,
  LogOut,
  Settings,
} from 'lucide-react';
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
} from '@/components/ui/sidebar';
import { Button } from '@/components/ui/button';

// Navigation items
const items = [
  {
    title: 'Dashboard',
    href: '/app',
    icon: LayoutDashboard,
  },
  {
    title: 'Links',
    href: '/app/links',
    icon: LinkIcon,
  },
  {
    title: 'Settings',
    href: '/app/settings',
    icon: Settings,
  },
];

export function AppSidebar() {
  const pathname = usePathname();

  const handleLogout = async () => {
    // Clear auth cookie and redirect
    document.cookie = 'auth-token=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT';
    window.location.href = '/auth/login';
  };

  return (
    <Sidebar>
      <SidebarHeader>
        <div className="flex h-14 items-center border-b px-6">
          <Link href="/app" className="flex items-center gap-2 font-semibold">
            <LinkIcon className="h-6 w-6" />
            <span>Shortify</span>
          </Link>
        </div>
      </SidebarHeader>
      
      <SidebarContent>
        <SidebarGroup>
          <SidebarGroupLabel>Application</SidebarGroupLabel>
          <SidebarGroupContent>
            <SidebarMenu>
              {items.map((item) => (
                <SidebarMenuItem key={item.href}>
                  <SidebarMenuButton
                    asChild
                    isActive={pathname === item.href}
                  >
                    <Link href={item.href}>
                      <item.icon className="h-4 w-4" />
                      <span>{item.title}</span>
                    </Link>
                  </SidebarMenuButton>
                </SidebarMenuItem>
              ))}
            </SidebarMenu>
          </SidebarGroupContent>
        </SidebarGroup>
      </SidebarContent>

      <SidebarFooter>
        <div className="p-4">
          <Button
            variant="outline"
            className="w-full justify-start"
            onClick={handleLogout}
          >
            <LogOut className="mr-2 h-4 w-4" />
            Logout
          </Button>
        </div>
      </SidebarFooter>
    </Sidebar>
  );
}
```

### Understanding the Sidebar

**1. Navigation Items**: The `items` array defines all navigation links with titles, paths, and icons from `lucide-react`.

**2. Active State**: `pathname === item.href` highlights the current page in the navigation.

**3. Logout Handler**: Clears the auth cookie and redirects to login. This is a simple client-side logout.

**4. Responsive**: The sidebar automatically collapses on mobile using the Shadcn UI sidebar component.

## Creating the Dashboard Overview Page

The dashboard overview shows analytics at a glance: total links, total clicks, click-through rate, and recent activity. This gives users immediate insight into their link performance.

Create `src/app/app/page.tsx`:

```typescript
'use client';

import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from '@/components/ui/table';
import { Badge } from '@/components/ui/badge';
import { Button } from '@/components/ui/button';
import { ArrowUpRight, Link as LinkIcon, MousePointerClick } from 'lucide-react';
import Link from 'next/link';
import { api } from '@/igniter.client';

export default function DashboardPage() {
  // Fetch analytics data
  const { data: stats, isLoading: statsLoading } = api.link.getStats.useQuery();
  
  // Fetch recent links
  const { data: recentLinks, isLoading: linksLoading } = api.link.list.useQuery({
    query: {
      limit: '5',
      orderBy: 'createdAt',
      order: 'desc',
    },
  });

  // Calculate analytics
  const totalLinks = stats?.totalLinks || 0;
  const totalClicks = stats?.totalClicks || 0;
  const clickThroughRate = totalLinks > 0 ? ((totalClicks / totalLinks) * 100).toFixed(1) : '0';

  return (
    <div className="flex flex-1 flex-col gap-4">
      <div className="flex items-center justify-between">
        <h1 className="text-3xl font-bold">Dashboard</h1>
      </div>

      {/* Analytics Cards */}
      <div className="grid gap-4 md:grid-cols-3">
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">Total Links</CardTitle>
            <LinkIcon className="h-4 w-4 text-muted-foreground" />
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">
              {statsLoading ? '...' : totalLinks}
            </div>
            <p className="text-xs text-muted-foreground">
              Active shortened links
            </p>
          </CardContent>
        </Card>

        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">Total Clicks</CardTitle>
            <MousePointerClick className="h-4 w-4 text-muted-foreground" />
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">
              {statsLoading ? '...' : totalClicks}
            </div>
            <p className="text-xs text-muted-foreground">
              All-time clicks across links
            </p>
          </CardContent>
        </Card>

        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">
              Average CTR
            </CardTitle>
            <ArrowUpRight className="h-4 w-4 text-muted-foreground" />
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">
              {statsLoading ? '...' : `${clickThroughRate}%`}
            </div>
            <p className="text-xs text-muted-foreground">
              Click-through rate
            </p>
          </CardContent>
        </Card>
      </div>

      {/* Recent Links Table */}
      <Card>
        <CardHeader>
          <div className="flex items-center justify-between">
            <CardTitle>Recent Links</CardTitle>
            <Button asChild size="sm">
              <Link href="/app/links">
                View All
                <ArrowUpRight className="ml-2 h-4 w-4" />
              </Link>
            </Button>
          </div>
        </CardHeader>
        <CardContent>
          {linksLoading ? (
            <div className="text-center py-8 text-muted-foreground">
              Loading links...
            </div>
          ) : recentLinks?.links?.length === 0 ? (
            <div className="text-center py-8 text-muted-foreground">
              <p className="mb-2">No links yet</p>
              <Button asChild size="sm">
                <Link href="/app/links">Create your first link</Link>
              </Button>
            </div>
          ) : (
            <Table>
              <TableHeader>
                <TableRow>
                  <TableHead>Short URL</TableHead>
                  <TableHead>Destination</TableHead>
                  <TableHead>Clicks</TableHead>
                  <TableHead>Status</TableHead>
                </TableRow>
              </TableHeader>
              <TableBody>
                {recentLinks?.links?.map((link) => (
                  <TableRow key={link.id}>
                    <TableCell className="font-medium">
                      <Link
                        href={`/${link.slug}`}
                        className="hover:underline text-primary"
                        target="_blank"
                      >
                        /{link.slug}
                      </Link>
                    </TableCell>
                    <TableCell className="max-w-md truncate">
                      {link.url}
                    </TableCell>
                    <TableCell>{link.clicks.length}</TableCell>
                    <TableCell>
                      <Badge variant={link.isActive ? 'default' : 'secondary'}>
                        {link.isActive ? 'Active' : 'Inactive'}
                      </Badge>
                    </TableCell>
                  </TableRow>
                ))}
              </TableBody>
            </Table>
          )}
        </CardContent>
      </Card>
    </div>
  );
}
```

### Understanding the Dashboard Overview

**1. Analytics Cards**: Three cards show key metrics using `useQuery` hooks. The loading states ensure a smooth UX while data loads.

**2. Stats Calculation**: We calculate the click-through rate client-side from the stats data.

**3. Recent Links Table**: Displays the 5 most recent links with truncated URLs and click counts.

**4. Empty State**: Shows a helpful message when there are no links yet, with a CTA to create the first one.

**5. Type Safety**: All data is fully typed thanks to the Igniter.js client—no manual type definitions needed.

## Creating the Links Management Page

The links page displays all links in a filterable, sortable table with actions for creating, editing, and deleting links. This is the main interface for managing shortened URLs.

Create `src/app/app/links/page.tsx`:

```typescript
'use client';

import { useState } from 'react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from '@/components/ui/table';
import { Badge } from '@/components/ui/badge';
import { Button } from '@/components/ui/button';
import { Plus, Pencil, Trash2, Copy, ExternalLink } from 'lucide-react';
import { api } from '@/igniter.client';
import { toast } from 'sonner';
import { CreateLinkDialog } from '@/features/link/presentation/components/create-link-dialog';
import { EditLinkDialog } from '@/features/link/presentation/components/edit-link-dialog';
import { DeleteLinkDialog } from '@/features/link/presentation/components/delete-link-dialog';

export default function LinksPage() {
  const [createDialogOpen, setCreateDialogOpen] = useState(false);
  const [editDialogOpen, setEditDialogOpen] = useState(false);
  const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
  const [selectedLinkId, setSelectedLinkId] = useState<string | null>(null);

  // Fetch all links
  const { data, isLoading, refetch } = api.link.list.useQuery({
    query: {
      orderBy: 'createdAt',
      order: 'desc',
    },
  });

  const handleCopyLink = (slug: string) => {
    const fullUrl = `${window.location.origin}/${slug}`;
    navigator.clipboard.writeText(fullUrl);
    toast.success('Link copied!', {
      description: 'The shortened link has been copied to your clipboard.',
    });
  };

  const handleEdit = (id: string) => {
    setSelectedLinkId(id);
    setEditDialogOpen(true);
  };

  const handleDelete = (id: string) => {
    setSelectedLinkId(id);
    setDeleteDialogOpen(true);
  };

  const handleSuccess = () => {
    refetch();
    setCreateDialogOpen(false);
    setEditDialogOpen(false);
    setDeleteDialogOpen(false);
    setSelectedLinkId(null);
  };

  return (
    <div className="flex flex-1 flex-col gap-4">
      <div className="flex items-center justify-between">
        <h1 className="text-3xl font-bold">Links</h1>
        <Button onClick={() => setCreateDialogOpen(true)}>
          <Plus className="mr-2 h-4 w-4" />
          Create Link
        </Button>
      </div>

      <Card>
        <CardHeader>
          <CardTitle>All Links</CardTitle>
        </CardHeader>
        <CardContent>
          {isLoading ? (
            <div className="text-center py-8 text-muted-foreground">
              Loading links...
            </div>
          ) : data?.links?.length === 0 ? (
            <div className="text-center py-8">
              <p className="text-muted-foreground mb-4">
                No links created yet
              </p>
              <Button onClick={() => setCreateDialogOpen(true)}>
                <Plus className="mr-2 h-4 w-4" />
                Create your first link
              </Button>
            </div>
          ) : (
            <Table>
              <TableHeader>
                <TableRow>
                  <TableHead>Short URL</TableHead>
                  <TableHead>Destination</TableHead>
                  <TableHead>Clicks</TableHead>
                  <TableHead>Status</TableHead>
                  <TableHead className="text-right">Actions</TableHead>
                </TableRow>
              </TableHeader>
              <TableBody>
                {data?.links?.map((link) => (
                  <TableRow key={link.id}>
                    <TableCell className="font-medium">
                      <div className="flex items-center gap-2">
                        <a
                          href={`/${link.slug}`}
                          className="hover:underline text-primary"
                          target="_blank"
                          rel="noopener noreferrer"
                        >
                          /{link.slug}
                        </a>
                        <Button
                          variant="ghost"
                          size="icon"
                          className="h-6 w-6"
                          onClick={() => handleCopyLink(link.slug)}
                        >
                          <Copy className="h-3 w-3" />
                        </Button>
                      </div>
                    </TableCell>
                    <TableCell className="max-w-md">
                      <div className="flex items-center gap-2">
                        <span className="truncate">{link.url}</span>
                        <a
                          href={link.url}
                          target="_blank"
                          rel="noopener noreferrer"
                          className="shrink-0"
                        >
                          <ExternalLink className="h-3 w-3 text-muted-foreground" />
                        </a>
                      </div>
                    </TableCell>
                    <TableCell>{link.clicks.length}</TableCell>
                    <TableCell>
                      <Badge variant={link.isActive ? 'default' : 'secondary'}>
                        {link.isActive ? 'Active' : 'Inactive'}
                      </Badge>
                    </TableCell>
                    <TableCell className="text-right">
                      <div className="flex justify-end gap-2">
                        <Button
                          variant="ghost"
                          size="icon"
                          onClick={() => handleEdit(link.id)}
                        >
                          <Pencil className="h-4 w-4" />
                        </Button>
                        <Button
                          variant="ghost"
                          size="icon"
                          onClick={() => handleDelete(link.id)}
                        >
                          <Trash2 className="h-4 w-4 text-destructive" />
                        </Button>
                      </div>
                    </TableCell>
                  </TableRow>
                ))}
              </TableBody>
            </Table>
          )}
        </CardContent>
      </Card>

      {/* Dialogs */}
      <CreateLinkDialog
        open={createDialogOpen}
        onOpenChange={setCreateDialogOpen}
        onSuccess={handleSuccess}
      />
      
      {selectedLinkId && (
        <>
          <EditLinkDialog
            open={editDialogOpen}
            onOpenChange={setEditDialogOpen}
            linkId={selectedLinkId}
            onSuccess={handleSuccess}
          />
          
          <DeleteLinkDialog
            open={deleteDialogOpen}
            onOpenChange={setDeleteDialogOpen}
            linkId={selectedLinkId}
            onSuccess={handleSuccess}
          />
        </>
      )}
    </div>
  );
}
```

### Understanding the Links Page

**1. State Management**: Local state tracks which dialog is open and which link is being edited/deleted.

**2. Copy to Clipboard**: The copy button uses the Clipboard API to copy the shortened URL.

**3. Refetch Pattern**: After any mutation (create/edit/delete), we call `refetch()` to update the table with fresh data.

**4. Actions Column**: Each row has edit and delete buttons that open the appropriate dialog.

**5. External Link Icons**: Both the short URL and destination URL have icons for opening in new tabs.

## Creating the Link Dialogs

Now let's create the three dialogs for CRUD operations. Each dialog is self-contained with its own form, validation, and mutation logic.

### Create Link Dialog

Create `src/features/link/presentation/components/create-link-dialog.tsx`:

```typescript
'use client';

import { Controller, useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { toast } from 'sonner';
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
} from '@/components/ui/dialog';
import {
  Field,
  FieldError,
  FieldGroup,
  FieldLabel,
} from '@/components/ui/field';
import { Input } from '@/components/ui/input';
import { Button } from '@/components/ui/button';
import { api } from '@/igniter.client';

const createLinkSchema = z.object({
  url: z
    .string()
    .min(1, 'URL is required')
    .url('Enter a valid URL'),
  slug: z
    .string()
    .min(1, 'Slug is required')
    .min(3, 'Slug must be at least 3 characters')
    .max(50, 'Slug must be less than 50 characters')
    .regex(/^[a-z0-9-]+$/, 'Slug can only contain lowercase letters, numbers, and hyphens'),
});

type CreateLinkFormData = z.infer<typeof createLinkSchema>;

interface CreateLinkDialogProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  onSuccess: () => void;
}

export function CreateLinkDialog({
  open,
  onOpenChange,
  onSuccess,
}: CreateLinkDialogProps) {
  const form = useForm<CreateLinkFormData>({
    resolver: zodResolver(createLinkSchema),
    defaultValues: {
      url: '',
      slug: '',
    },
  });

  const createMutation = api.link.create.useMutation({
    onSuccess: () => {
      toast.success('Link created!', {
        description: 'Your shortened link is ready to use.',
      });
      form.reset();
      onSuccess();
    },
    onError: (error) => {
      toast.error('Failed to create link', {
        description: error.message || 'Please try again.',
      });
    },
  });

  const onSubmit = async (data: CreateLinkFormData) => {
    await createMutation.mutate({
      body: {
        url: data.url,
        slug: data.slug,
        isActive: true,
      },
    });
  };

  return (
    <Dialog open={open} onOpenChange={onOpenChange}>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Create New Link</DialogTitle>
          <DialogDescription>
            Create a shortened link for your URL
          </DialogDescription>
        </DialogHeader>

        <form onSubmit={form.handleSubmit(onSubmit)}>
          <FieldGroup>
            <Controller
              name="url"
              control={form.control}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid}>
                  <FieldLabel htmlFor="url">Destination URL</FieldLabel>
                  <Input
                    {...field}
                    id="url"
                    type="url"
                    placeholder="https://example.com/very/long/url"
                    aria-invalid={fieldState.invalid}
                  />
                  {fieldState.invalid && (
                    <FieldError errors={[fieldState.error]} />
                  )}
                </Field>
              )}
            />

            <Controller
              name="slug"
              control={form.control}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid}>
                  <FieldLabel htmlFor="slug">Custom Slug</FieldLabel>
                  <div className="flex items-center gap-2">
                    <span className="text-sm text-muted-foreground">/</span>
                    <Input
                      {...field}
                      id="slug"
                      type="text"
                      placeholder="my-link"
                      aria-invalid={fieldState.invalid}
                    />
                  </div>
                  {fieldState.invalid && (
                    <FieldError errors={[fieldState.error]} />
                  )}
                </Field>
              )}
            />

            <div className="flex justify-end gap-2 mt-4">
              <Button
                type="button"
                variant="outline"
                onClick={() => onOpenChange(false)}
              >
                Cancel
              </Button>
              <Button type="submit" disabled={createMutation.isLoading}>
                {createMutation.isLoading ? 'Creating...' : 'Create Link'}
              </Button>
            </div>
          </FieldGroup>
        </form>
      </DialogContent>
    </Dialog>
  );
}
```

### Edit Link Dialog

Create `src/features/link/presentation/components/edit-link-dialog.tsx`:

```typescript
'use client';

import { useEffect } from 'react';
import { Controller, useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { toast } from 'sonner';
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
} from '@/components/ui/dialog';
import {
  Field,
  FieldError,
  FieldGroup,
  FieldLabel,
} from '@/components/ui/field';
import { Input } from '@/components/ui/input';
import { Button } from '@/components/ui/button';
import { Switch } from '@/components/ui/switch';
import { api } from '@/igniter.client';

const editLinkSchema = z.object({
  url: z
    .string()
    .min(1, 'URL is required')
    .url('Enter a valid URL'),
  isActive: z.boolean(),
});

type EditLinkFormData = z.infer<typeof editLinkSchema>;

interface EditLinkDialogProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  linkId: string;
  onSuccess: () => void;
}

export function EditLinkDialog({
  open,
  onOpenChange,
  linkId,
  onSuccess,
}: EditLinkDialogProps) {
  // Fetch link data
  const { data: link, isLoading } = api.link.getById.useQuery({
    params: { id: linkId },
  });

  const form = useForm<EditLinkFormData>({
    resolver: zodResolver(editLinkSchema),
    defaultValues: {
      url: '',
      isActive: true,
    },
  });

  // Update form when link data loads
  useEffect(() => {
    if (link) {
      form.reset({
        url: link.url,
        isActive: link.isActive,
      });
    }
  }, [link, form]);

  const updateMutation = api.link.update.useMutation({
    onSuccess: () => {
      toast.success('Link updated!', {
        description: 'Your changes have been saved.',
      });
      onSuccess();
    },
    onError: (error) => {
      toast.error('Failed to update link', {
        description: error.message || 'Please try again.',
      });
    },
  });

  const onSubmit = async (data: EditLinkFormData) => {
    await updateMutation.mutate({
      params: { id: linkId },
      body: {
        url: data.url,
        isActive: data.isActive,
      },
    });
  };

  return (
    <Dialog open={open} onOpenChange={onOpenChange}>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Edit Link</DialogTitle>
          <DialogDescription>
            Update your link settings
          </DialogDescription>
        </DialogHeader>

        {isLoading ? (
          <div className="py-8 text-center text-muted-foreground">
            Loading link...
          </div>
        ) : (
          <form onSubmit={form.handleSubmit(onSubmit)}>
            <FieldGroup>
              <Controller
                name="url"
                control={form.control}
                render={({ field, fieldState }) => (
                  <Field data-invalid={fieldState.invalid}>
                    <FieldLabel htmlFor="edit-url">Destination URL</FieldLabel>
                    <Input
                      {...field}
                      id="edit-url"
                      type="url"
                      placeholder="https://example.com"
                      aria-invalid={fieldState.invalid}
                    />
                    {fieldState.invalid && (
                      <FieldError errors={[fieldState.error]} />
                    )}
                  </Field>
                )}
              />

              <Controller
                name="isActive"
                control={form.control}
                render={({ field }) => (
                  <Field>
                    <div className="flex items-center justify-between">
                      <FieldLabel htmlFor="edit-active">
                        Link Status
                      </FieldLabel>
                      <Switch
                        id="edit-active"
                        checked={field.value}
                        onCheckedChange={field.onChange}
                      />
                    </div>
                    <p className="text-xs text-muted-foreground">
                      {field.value ? 'Link is active' : 'Link is inactive'}
                    </p>
                  </Field>
                )}
              />

              <div className="flex justify-end gap-2 mt-4">
                <Button
                  type="button"
                  variant="outline"
                  onClick={() => onOpenChange(false)}
                >
                  Cancel
                </Button>
                <Button type="submit" disabled={updateMutation.isLoading}>
                  {updateMutation.isLoading ? 'Saving...' : 'Save Changes'}
                </Button>
              </div>
            </FieldGroup>
          </form>
        )}
      </DialogContent>
    </Dialog>
  );
}
```

### Delete Link Dialog

Create `src/features/link/presentation/components/delete-link-dialog.tsx`:

```typescript
'use client';

import { toast } from 'sonner';
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
} from '@/components/ui/dialog';
import { Button } from '@/components/ui/button';
import { api } from '@/igniter.client';

interface DeleteLinkDialogProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  linkId: string;
  onSuccess: () => void;
}

export function DeleteLinkDialog({
  open,
  onOpenChange,
  linkId,
  onSuccess,
}: DeleteLinkDialogProps) {
  const deleteMutation = api.link.delete.useMutation({
    onSuccess: () => {
      toast.success('Link deleted!', {
        description: 'The link has been permanently removed.',
      });
      onSuccess();
    },
    onError: (error) => {
      toast.error('Failed to delete link', {
        description: error.message || 'Please try again.',
      });
    },
  });

  const handleDelete = async () => {
    await deleteMutation.mutate({
      params: { id: linkId },
    });
  };

  return (
    <Dialog open={open} onOpenChange={onOpenChange}>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Delete Link</DialogTitle>
          <DialogDescription>
            Are you sure you want to delete this link? This action cannot be undone.
            All analytics data for this link will also be removed.
          </DialogDescription>
        </DialogHeader>

        <DialogFooter>
          <Button
            variant="outline"
            onClick={() => onOpenChange(false)}
          >
            Cancel
          </Button>
          <Button
            variant="destructive"
            onClick={handleDelete}
            disabled={deleteMutation.isLoading}
          >
            {deleteMutation.isLoading ? 'Deleting...' : 'Delete Link'}
          </Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}
```

### Understanding the Dialogs

**1. Create Dialog**: Simple form with URL and slug validation. The slug regex ensures it's URL-safe.

**2. Edit Dialog**: Fetches existing data with `useQuery`, then populates the form with `useEffect`. Includes a toggle for active/inactive status.

**3. Delete Dialog**: Confirmation dialog with a destructive action. No form needed—just a confirmation.

**4. Consistent Pattern**: All three dialogs follow the same pattern: schema, form, mutation, success/error handling.

## Testing the Dashboard

Start your development server:

```bash
igniter dev
```

Now test the complete dashboard:

1. **Navigate to `/app`** after logging in
   * You should see the dashboard with analytics cards
   * If you have links, the recent links table appears
   * If no links exist, you see an empty state with a CTA

2. **Click "Create Link"** or navigate to `/app/links`
   * The create dialog opens
   * Enter a URL and custom slug
   * Click "Create Link"
   * The dialog closes and the table updates automatically

3. **Edit a link**
   * Click the pencil icon on any link
   * Change the URL or toggle the active status
   * Click "Save Changes"
   * The table updates with the new data

4. **Delete a link**
   * Click the trash icon on any link
   * Confirm the deletion
   * The link disappears from the table

5. **Copy a link**
   * Click the copy icon next to any short URL
   * You should see a success toast
   * Paste to verify the full URL was copied

<Callout type="success" title="Dashboard Complete!">
  You now have a fully functional dashboard with:

  * Professional layout with sidebar navigation
  * Analytics overview with real-time stats
  * Link management with full CRUD operations
  * Type-safe data fetching with Igniter.js hooks
  * Beautiful UI components from Shadcn UI
</Callout>

## Key Concepts Review

**1. Dashboard Layout**: The sidebar layout pattern provides consistent navigation across the app. The `SidebarProvider` manages state for responsive behavior.

**2. Data Fetching with Hooks**: The `useQuery` hook fetches data reactively. When you call `refetch()`, it automatically updates all components using that data.

**3. Mutations**: The `useMutation` hook handles create, update, and delete operations. It provides loading states and error handling out of the box.

**4. Dialog Pattern**: Dialogs are controlled components. State in the parent component determines which dialog is open and which item is being edited.

**5. Optimistic Updates**: After mutations, we call `refetch()` to ensure the UI shows the latest data. In production, you might use optimistic updates for instant feedback.

## Quiz

<Quiz
  question="Why do we call refetch() after mutations?"
  options={[
  { label: 'To reset the form', value: 'reset' },
  { label: 'To update the table with fresh data from the server', value: 'refresh', isCorrect: true },
  { label: 'To close the dialog', value: 'close' },
  { label: 'To show a loading state', value: 'loading' }
]}
  explanation="After creating, updating, or deleting a link, we call refetch() to fetch the latest data from the server. This ensures the table displays accurate information without needing a page reload."
/>

<Quiz
  question="What does the SidebarProvider component do?"
  options={[
  { label: 'Fetches sidebar data from the API', value: 'fetch' },
  { label: 'Manages sidebar state and provides context to children', value: 'state', isCorrect: true },
  { label: 'Renders the sidebar navigation', value: 'render' },
  { label: 'Handles authentication for sidebar routes', value: 'auth' }
]}
  explanation="The SidebarProvider manages the sidebar state (open/closed) and provides that state to child components through React context. This allows the sidebar to respond to user interactions and screen size changes."
/>

<ChapterNav
  current={{ number: 6, title: 'Link Management UI' }}
  next={{
  number: 7,
  title: 'Click Tracking & Analytics',
  description: 'Implement click tracking, capture visitor data, and build analytics visualizations with charts.',
  href: '/learn/07-click-tracking-analytics'
}}
/>


---

# 07: Click Tracking & Analytics

> Implement click tracking, capture visitor data, and build interactive analytics dashboards with charts and geographic insights.
URL: https://igniterjs.com/learn/course/07-click-tracking-analytics

In this chapter, we'll add comprehensive analytics to Shortify. You'll learn how to track clicks, capture visitor information (location, device, browser), and create beautiful visualizations to help users understand their link performance.

<ChapterObjectives
  objectives={[
{ text: "Create a redirect endpoint that tracks clicks before redirecting" },
{ text: "Capture visitor metadata (IP, user agent, referrer)" },
{ text: "Parse user agent data to extract device and browser information" },
{ text: "Build an analytics page with charts using Recharts" },
{ text: "Display geographic data and top-performing links" }
]}
/>

## Understanding Click Tracking

When someone visits a shortened link (`/my-link`), we need to:

1. **Record the click** - Save it to the database with metadata
2. **Extract visitor data** - Parse IP, user agent, referrer
3. **Redirect** - Send the user to the destination URL

This must happen **fast**—users shouldn't notice any delay. We'll use an efficient approach that records the click and redirects immediately.

## Creating the Redirect Route

Next.js App Router allows us to create API routes as Route Handlers. We'll create a catch-all route that handles all shortened URLs.

Create `src/app/[slug]/route.ts`:

```typescript
import { NextRequest, NextResponse } from 'next/server';
import { db } from '@/lib/database';

export async function GET(
  request: NextRequest,
  { params }: { params: { slug: string } }
) {
  const { slug } = params;

  try {
    // Find the link by slug
    const link = await db.link.findUnique({
      where: { slug },
      select: {
        id: true,
        url: true,
        isActive: true,
      },
    });

    // If link doesn't exist or is inactive, show 404
    if (!link || !link.isActive) {
      return NextResponse.json(
        { error: 'Link not found' },
        { status: 404 }
      );
    }

    // Extract visitor metadata
    const ip = request.ip || 
               request.headers.get('x-forwarded-for')?.split(',')[0] || 
               request.headers.get('x-real-ip') || 
               'unknown';
    
    const userAgent = request.headers.get('user-agent') || 'unknown';
    const referrer = request.headers.get('referer') || null;

    // Record the click asynchronously (don't wait for it)
    // This ensures the redirect happens immediately
    db.click.create({
      data: {
        linkId: link.id,
        ip,
        userAgent,
        referrer,
      },
    }).catch((error) => {
      // Log the error but don't block the redirect
      console.error('Failed to record click:', error);
    });

    // Redirect to the destination URL
    return NextResponse.redirect(link.url, { status: 307 });
    
  } catch (error) {
    console.error('Error in redirect route:', error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}
```

### Understanding the Redirect Route

**1. Catch-All Route**: The `[slug]` folder name makes this route match any path (e.g., `/my-link`, `/promo2024`).

**2. Link Lookup**: We query the database for the link, selecting only the fields we need for efficiency.

**3. Metadata Extraction**:

* **IP Address**: Tries multiple headers because proxies/load balancers use different headers
* **User Agent**: Contains browser, OS, and device information
* **Referrer**: Shows where the user came from (if available)

**4. Async Click Recording**: We use `.catch()` instead of `await` so the redirect happens immediately without waiting for the database write.

**5. 307 Redirect**: A temporary redirect that preserves the HTTP method (GET in this case).

<Callout type="info" title="Why Async Recording?">
  Recording the click asynchronously means users get redirected instantly. The click data is saved in the background. If it fails, we log the error but don't impact the user experience.
</Callout>

## Enhancing Click Data with User Agent Parsing

The raw user agent string contains useful information, but it's hard to read. Let's parse it to extract device type, browser, and OS information.

First, install a user agent parser:

```bash
npm install ua-parser-js
npm install -D @types/ua-parser-js
```

Now update the redirect route to parse user agent data:

```typescript
import { NextRequest, NextResponse } from 'next/server';
import { UAParser } from 'ua-parser-js';
import { db } from '@/lib/database';

export async function GET(
  request: NextRequest,
  { params }: { params: { slug: string } }
) {
  const { slug } = params;

  try {
    const link = await db.link.findUnique({
      where: { slug },
      select: {
        id: true,
        url: true,
        isActive: true,
      },
    });

    if (!link || !link.isActive) {
      return NextResponse.json(
        { error: 'Link not found' },
        { status: 404 }
      );
    }

    // Extract metadata
    const ip = request.ip || 
               request.headers.get('x-forwarded-for')?.split(',')[0] || 
               request.headers.get('x-real-ip') || 
               'unknown';
    
    const userAgent = request.headers.get('user-agent') || 'unknown';
    const referrer = request.headers.get('referer') || null;

    // Parse user agent to extract device/browser/OS info
    const parser = new UAParser(userAgent);
    const uaResult = parser.getResult();

    // Record click with parsed data
    db.click.create({
      data: {
        linkId: link.id,
        ip,
        userAgent,
        referrer,
        // Parsed user agent data
        browser: uaResult.browser.name || null,
        browserVersion: uaResult.browser.version || null,
        os: uaResult.os.name || null,
        osVersion: uaResult.os.version || null,
        device: uaResult.device.type || 'desktop',
        deviceModel: uaResult.device.model || null,
      },
    }).catch((error) => {
      console.error('Failed to record click:', error);
    });

    return NextResponse.redirect(link.url, { status: 307 });
    
  } catch (error) {
    console.error('Error in redirect route:', error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}
```

### Understanding User Agent Parsing

**1. UAParser**: A lightweight library that parses user agent strings into structured data.

**2. Extracted Data**:

* **Browser**: Chrome, Safari, Firefox, etc.
* **OS**: Windows, macOS, iOS, Android, etc.
* **Device**: mobile, tablet, desktop

**3. Database Fields**: Make sure your Prisma schema has these optional fields in the `Click` model (they should already exist from Chapter 2).

## Adding Analytics Endpoints to the Link Controller

Now let's add actions to fetch analytics data. We'll create endpoints for overall stats and per-link analytics.

Open `src/features/link/link.controller.ts` and add these new actions:

```typescript
// Add this to your existing link controller

// Get overall analytics stats
getStats: igniter.action({
  use: [authProcedure],
  handler: async ({ context }) => {
    const userId = context.auth.session.user!.id;

    // Get all user's links
    const links = await context.db.link.findMany({
      where: { userId },
      include: {
        clicks: true,
      },
    });

    const totalLinks = links.length;
    const totalClicks = links.reduce((sum, link) => sum + link.clicks.length, 0);

    return context.response.ok({
      totalLinks,
      totalClicks,
    });
  },
}),

// Get analytics for a specific link
getLinkAnalytics: igniter.action({
  use: [authProcedure],
  input: z.object({
    id: z.string(),
  }),
  handler: async ({ input, context }) => {
    const userId = context.auth.session.user!.id;

    // Get link with all clicks
    const link = await context.db.link.findFirst({
      where: {
        id: input.id,
        userId,
      },
      include: {
        clicks: {
          orderBy: {
            createdAt: 'desc',
          },
        },
      },
    });

    if (!link) {
      return context.response.notFound({
        message: 'Link not found',
      });
    }

    // Aggregate analytics data
    const totalClicks = link.clicks.length;
    
    // Group by browser
    const browserStats = link.clicks.reduce((acc, click) => {
      const browser = click.browser || 'Unknown';
      acc[browser] = (acc[browser] || 0) + 1;
      return acc;
    }, {} as Record<string, number>);

    // Group by device
    const deviceStats = link.clicks.reduce((acc, click) => {
      const device = click.device || 'desktop';
      acc[device] = (acc[device] || 0) + 1;
      return acc;
    }, {} as Record<string, number>);

    // Group by OS
    const osStats = link.clicks.reduce((acc, click) => {
      const os = click.os || 'Unknown';
      acc[os] = (acc[os] || 0) + 1;
      return acc;
    }, {} as Record<string, number>);

    // Clicks over time (last 7 days)
    const sevenDaysAgo = new Date();
    sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);

    const recentClicks = link.clicks.filter(
      (click) => new Date(click.createdAt) >= sevenDaysAgo
    );

    // Group by date
    const clicksByDate = recentClicks.reduce((acc, click) => {
      const date = new Date(click.createdAt).toISOString().split('T')[0];
      acc[date] = (acc[date] || 0) + 1;
      return acc;
    }, {} as Record<string, number>);

    // Top referrers
    const referrerStats = link.clicks
      .filter((click) => click.referrer)
      .reduce((acc, click) => {
        const referrer = click.referrer!;
        acc[referrer] = (acc[referrer] || 0) + 1;
        return acc;
      }, {} as Record<string, number>);

    return context.response.ok({
      link: {
        id: link.id,
        slug: link.slug,
        url: link.url,
      },
      totalClicks,
      browserStats,
      deviceStats,
      osStats,
      clicksByDate,
      referrerStats,
    });
  },
}),
```

### Understanding the Analytics Actions

**1. getStats**: Returns overall statistics for the dashboard overview (total links, total clicks).

**2. getLinkAnalytics**: Returns detailed analytics for a specific link:

* **Browser distribution**: How many clicks from each browser
* **Device distribution**: Mobile vs tablet vs desktop
* **OS distribution**: Windows, macOS, iOS, Android, etc.
* **Clicks over time**: Daily click count for the last 7 days
* **Top referrers**: Where traffic is coming from

**3. Data Aggregation**: We use `reduce()` to group clicks by different dimensions. This happens in-memory for speed.

## Installing Chart Components

For visualizations, we'll use Recharts—a composable charting library built on React components.

```bash
npm install recharts
```

Also install the Shadcn UI chart components wrapper:

```bash
npx shadcn@latest add chart
```

## Creating the Link Analytics Page

Now let's create a dedicated analytics page for each link. This page will show detailed metrics with beautiful charts.

Create `src/app/app/links/[id]/analytics/page.tsx`:

```typescript
'use client';

import { use } from 'react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { ArrowLeft, TrendingUp } from 'lucide-react';
import Link from 'next/link';
import { api } from '@/igniter.client';
import {
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
} from '@/components/ui/chart';
import {
  Bar,
  BarChart,
  Line,
  LineChart,
  Pie,
  PieChart,
  Cell,
  XAxis,
  YAxis,
  CartesianGrid,
  Legend,
  ResponsiveContainer,
} from 'recharts';

const COLORS = ['#0088FE', '#00C49F', '#FFBB28', '#FF8042', '#8884D8'];

export default function LinkAnalyticsPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = use(params);

  const { data, isLoading } = api.link.getLinkAnalytics.useQuery({
    body: { id },
  });

  if (isLoading) {
    return (
      <div className="flex flex-1 items-center justify-center">
        <p className="text-muted-foreground">Loading analytics...</p>
      </div>
    );
  }

  if (!data) {
    return (
      <div className="flex flex-1 flex-col items-center justify-center gap-4">
        <p className="text-muted-foreground">Link not found</p>
        <Button asChild>
          <Link href="/app/links">Back to Links</Link>
        </Button>
      </div>
    );
  }

  // Transform data for charts
  const browserData = Object.entries(data.browserStats).map(([name, value]) => ({
    name,
    value,
  }));

  const deviceData = Object.entries(data.deviceStats).map(([name, value]) => ({
    name,
    value,
  }));

  const osData = Object.entries(data.osStats).map(([name, value]) => ({
    name,
    value,
  }));

  const clicksOverTimeData = Object.entries(data.clicksByDate)
    .map(([date, clicks]) => ({
      date,
      clicks,
    }))
    .sort((a, b) => a.date.localeCompare(b.date));

  const topReferrers = Object.entries(data.referrerStats)
    .map(([url, clicks]) => ({
      url,
      clicks,
    }))
    .sort((a, b) => b.clicks - a.clicks)
    .slice(0, 5);

  return (
    <div className="flex flex-1 flex-col gap-4">
      {/* Header */}
      <div className="flex items-center gap-4">
        <Button variant="ghost" size="icon" asChild>
          <Link href="/app/links">
            <ArrowLeft className="h-4 w-4" />
          </Link>
        </Button>
        <div className="flex-1">
          <h1 className="text-3xl font-bold">Link Analytics</h1>
          <p className="text-muted-foreground">/{data.link.slug}</p>
        </div>
      </div>

      {/* Stats Overview */}
      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
        <Card>
          <CardHeader>
            <CardTitle className="text-sm font-medium">Total Clicks</CardTitle>
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">{data.totalClicks}</div>
            <p className="text-xs text-muted-foreground">All-time clicks</p>
          </CardContent>
        </Card>

        <Card>
          <CardHeader>
            <CardTitle className="text-sm font-medium">
              Unique Browsers
            </CardTitle>
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">{browserData.length}</div>
            <p className="text-xs text-muted-foreground">Different browsers</p>
          </CardContent>
        </Card>

        <Card>
          <CardHeader>
            <CardTitle className="text-sm font-medium">
              Unique Devices
            </CardTitle>
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">{deviceData.length}</div>
            <p className="text-xs text-muted-foreground">Device types</p>
          </CardContent>
        </Card>
      </div>

      {/* Charts */}
      <div className="grid gap-4 md:grid-cols-2">
        {/* Clicks Over Time */}
        <Card>
          <CardHeader>
            <CardTitle>Clicks Over Time</CardTitle>
          </CardHeader>
          <CardContent>
            <ChartContainer
              config={{
                clicks: {
                  label: 'Clicks',
                  color: 'hsl(var(--chart-1))',
                },
              }}
              className="h-[300px]"
            >
              <ResponsiveContainer width="100%" height="100%">
                <LineChart data={clicksOverTimeData}>
                  <CartesianGrid strokeDasharray="3 3" />
                  <XAxis
                    dataKey="date"
                    tickFormatter={(value) => {
                      const date = new Date(value);
                      return `${date.getMonth() + 1}/${date.getDate()}`;
                    }}
                  />
                  <YAxis />
                  <ChartTooltip content={<ChartTooltipContent />} />
                  <Line
                    type="monotone"
                    dataKey="clicks"
                    stroke="var(--color-clicks)"
                    strokeWidth={2}
                  />
                </LineChart>
              </ResponsiveContainer>
            </ChartContainer>
          </CardContent>
        </Card>

        {/* Browser Distribution */}
        <Card>
          <CardHeader>
            <CardTitle>Browser Distribution</CardTitle>
          </CardHeader>
          <CardContent>
            <ChartContainer
              config={browserData.reduce((acc, item, index) => ({
                ...acc,
                [item.name]: {
                  label: item.name,
                  color: COLORS[index % COLORS.length],
                },
              }), {})}
              className="h-[300px]"
            >
              <ResponsiveContainer width="100%" height="100%">
                <PieChart>
                  <Pie
                    data={browserData}
                    cx="50%"
                    cy="50%"
                    labelLine={false}
                    label={({ name, percent }) =>
                      `${name} ${(percent * 100).toFixed(0)}%`
                    }
                    outerRadius={80}
                    fill="#8884d8"
                    dataKey="value"
                  >
                    {browserData.map((entry, index) => (
                      <Cell
                        key={`cell-${index}`}
                        fill={COLORS[index % COLORS.length]}
                      />
                    ))}
                  </Pie>
                  <ChartTooltip content={<ChartTooltipContent />} />
                </PieChart>
              </ResponsiveContainer>
            </ChartContainer>
          </CardContent>
        </Card>

        {/* Device Distribution */}
        <Card>
          <CardHeader>
            <CardTitle>Device Distribution</CardTitle>
          </CardHeader>
          <CardContent>
            <ChartContainer
              config={deviceData.reduce((acc, item, index) => ({
                ...acc,
                [item.name]: {
                  label: item.name,
                  color: COLORS[index % COLORS.length],
                },
              }), {})}
              className="h-[300px]"
            >
              <ResponsiveContainer width="100%" height="100%">
                <BarChart data={deviceData}>
                  <CartesianGrid strokeDasharray="3 3" />
                  <XAxis dataKey="name" />
                  <YAxis />
                  <ChartTooltip content={<ChartTooltipContent />} />
                  <Bar dataKey="value" fill="#8884d8">
                    {deviceData.map((entry, index) => (
                      <Cell
                        key={`cell-${index}`}
                        fill={COLORS[index % COLORS.length]}
                      />
                    ))}
                  </Bar>
                </BarChart>
              </ResponsiveContainer>
            </ChartContainer>
          </CardContent>
        </Card>

        {/* Operating System Distribution */}
        <Card>
          <CardHeader>
            <CardTitle>Operating System</CardTitle>
          </CardHeader>
          <CardContent>
            <ChartContainer
              config={osData.reduce((acc, item, index) => ({
                ...acc,
                [item.name]: {
                  label: item.name,
                  color: COLORS[index % COLORS.length],
                },
              }), {})}
              className="h-[300px]"
            >
              <ResponsiveContainer width="100%" height="100%">
                <BarChart data={osData}>
                  <CartesianGrid strokeDasharray="3 3" />
                  <XAxis dataKey="name" />
                  <YAxis />
                  <ChartTooltip content={<ChartTooltipContent />} />
                  <Bar dataKey="value" fill="#8884d8">
                    {osData.map((entry, index) => (
                      <Cell
                        key={`cell-${index}`}
                        fill={COLORS[index % COLORS.length]}
                      />
                    ))}
                  </Bar>
                </BarChart>
              </ResponsiveContainer>
            </ChartContainer>
          </CardContent>
        </Card>
      </div>

      {/* Top Referrers */}
      {topReferrers.length > 0 && (
        <Card>
          <CardHeader>
            <CardTitle>Top Referrers</CardTitle>
          </CardHeader>
          <CardContent>
            <div className="space-y-4">
              {topReferrers.map((referrer, index) => (
                <div key={index} className="flex items-center justify-between">
                  <div className="flex items-center gap-2">
                    <div className="flex h-8 w-8 items-center justify-center rounded-full bg-primary text-primary-foreground text-sm font-medium">
                      {index + 1}
                    </div>
                    <div className="flex flex-col">
                      <span className="text-sm font-medium truncate max-w-md">
                        {referrer.url}
                      </span>
                    </div>
                  </div>
                  <div className="flex items-center gap-2">
                    <span className="text-sm text-muted-foreground">
                      {referrer.clicks} clicks
                    </span>
                  </div>
                </div>
              ))}
            </div>
          </CardContent>
        </Card>
      )}
    </div>
  );
}
```

### Understanding the Analytics Page

**1. Data Transformation**: We transform the stats objects into arrays that Recharts can consume.

**2. Four Main Charts**:

* **Line Chart**: Shows click trends over the last 7 days
* **Pie Chart**: Browser distribution as percentages
* **Bar Chart (Devices)**: Visual comparison of mobile vs desktop vs tablet
* **Bar Chart (OS)**: Operating system distribution

**3. Top Referrers**: A ranked list showing where traffic originates.

**4. Responsive Charts**: All charts use `ResponsiveContainer` to adapt to screen sizes.

**5. Color Palette**: Consistent colors across all charts using the `COLORS` array.

## Adding Analytics Links to the Table

Let's update the links table to include a link to view analytics for each link.

Open `src/app/app/links/page.tsx` and update the actions column:

```typescript
// In the TableRow mapping, update the actions cell:

<TableCell className="text-right">
  <div className="flex justify-end gap-2">
    <Button
      variant="ghost"
      size="icon"
      asChild
    >
      <Link href={`/app/links/${link.id}/analytics`}>
        <TrendingUp className="h-4 w-4" />
      </Link>
    </Button>
    <Button
      variant="ghost"
      size="icon"
      onClick={() => handleEdit(link.id)}
    >
      <Pencil className="h-4 w-4" />
    </Button>
    <Button
      variant="ghost"
      size="icon"
      onClick={() => handleDelete(link.id)}
    >
      <Trash2 className="h-4 w-4 text-destructive" />
    </Button>
  </div>
</TableCell>
```

Don't forget to import the `TrendingUp` icon at the top:

```typescript
import { Plus, Pencil, Trash2, Copy, ExternalLink, TrendingUp } from 'lucide-react';
```

## Testing Click Tracking and Analytics

Start your development server:

```bash
igniter dev
```

Now test the complete analytics flow:

1. **Create a few test links** at `/app/links`

2. **Open shortened links in different browsers/devices**
   * Open `/your-slug` in Chrome
   * Open `/your-slug` on your phone
   * Open `/your-slug` in Safari (if available)
   * This simulates traffic from different sources

3. **View analytics** by clicking the chart icon on any link
   * You should see the clicks distributed across browsers
   * Device types should reflect desktop/mobile usage
   * The line chart shows clicks over time

4. **Test referrers** by sharing a link from another website
   * Create a simple HTML file with a link to your shortened URL
   * Open it in a browser and click
   * The referrer should appear in "Top Referrers"

5. **Check the dashboard** at `/app`
   * Total clicks should increase with each visit
   * Recent links table should update

<Callout type="success" title="Analytics Working!">
  You now have a complete analytics system that:

  * Tracks every click with detailed metadata
  * Parses user agents to identify browsers, devices, and OS
  * Provides beautiful visualizations with Recharts
  * Shows geographic insights (via IP) and referrer sources
  * Updates in real-time as new clicks come in
</Callout>

## Key Concepts Review

**1. Catch-All Routes**: Next.js `[slug]` routes match dynamic paths. We use this to handle all shortened URLs in one place.

**2. Async Operations**: Recording clicks asynchronously ensures redirects happen instantly without waiting for database writes.

**3. User Agent Parsing**: The `ua-parser-js` library extracts structured data from raw user agent strings.

**4. Data Aggregation**: We use `reduce()` to group clicks by dimensions (browser, device, OS) for analytics.

**5. Chart Components**: Recharts provides composable React components for building interactive charts with minimal code.

## Quiz

<Quiz
  question="Why do we record clicks asynchronously without awaiting?"
  options={[
  { label: 'To save database resources', value: 'resources' },
  { label: 'To make redirects instant without waiting for database writes', value: 'instant', isCorrect: true },
  { label: 'To prevent errors in the redirect', value: 'errors' },
  { label: 'To improve chart performance', value: 'charts' }
]}
  explanation="We don't await the click recording operation so users get redirected immediately. The click is saved in the background. If it fails, we log the error but don't impact the user experience."
/>

<Quiz
  question="What does the UAParser library do?"
  options={[
  { label: 'Parses URLs into components', value: 'url' },
  { label: 'Extracts browser, OS, and device data from user agent strings', value: 'ua', isCorrect: true },
  { label: 'Converts IP addresses to locations', value: 'ip' },
  { label: 'Generates unique user IDs', value: 'id' }
]}
  explanation="UAParser takes a raw user agent string (like 'Mozilla/5.0...') and extracts structured information about the browser (Chrome, Safari), operating system (Windows, iOS), and device type (mobile, desktop, tablet)."
/>

<ChapterNav
  current={{ number: 7, title: 'Click Tracking & Analytics' }}
  next={{
  number: 8,
  title: 'Adding Link Previews',
  description: 'Generate beautiful Open Graph previews for your shortened links to improve social media sharing.',
  href: '/learn/08-link-previews'
}}
/>


---

# 00: Introduction

> Learn how to build a production-ready SaaS application with Igniter.js and Next.js
URL: https://igniterjs.com/learn/course

Welcome to the Igniter.js course! In this **free, interactive course**, you'll learn how to build a full-stack SaaS application by creating a complete **link shortening service** from scratch.

## What You'll Build

Throughout this course, you'll build **Shortify** - a production-ready link shortening SaaS with real-world features:

* **🔐 Authentication** - Secure user registration and login with Better Auth
* **🔗 Link Management** - Create, edit, and delete shortened links with custom slugs
* **📊 Analytics Dashboard** - Track clicks, locations, devices, and user behavior
* **🤖 AI-Powered Features** - Generate smart slugs and suggestions using AI
* **💳 Subscription Plans** - Monetize with Stripe integration (Free, Pro, Enterprise)
* **⚡ High Performance** - Caching with Redis and background jobs with BullMQ
* **🚀 Production Ready** - Deploy to Vercel with proper monitoring and observability

By the end of this course, you'll have a **complete, deployable application** and the knowledge to build your own SaaS products with Igniter.js.

## What is Igniter.js?

**Igniter.js** is a modern, type-safe framework for building full-stack TypeScript applications. It provides:

* **End-to-end type safety** from database to UI
* **Developer-first experience** with excellent tooling and CLI
* **Framework agnostic** - works with Next.js, Vite, Remix, and more
* **Production ready** - built-in support for caching, jobs, telemetry, and monitoring
* **Plugin ecosystem** - easily extend with adapters for Redis, BullMQ, OpenTelemetry, and more

Think of it as the **backend framework you've been missing** - it brings the same level of type safety and developer experience to your API that you enjoy with modern frontend frameworks.

## How the Course Works

This isn't a passive tutorial where you copy and paste code. You'll **learn by building**, step by step:

### 1. **Setup & Scaffold**

Start with the Igniter.js CLI to create a new project with all the right tools configured for you.

### 2. **Build Features Incrementally**

Each chapter adds new functionality to your application:

* Design your database schema
* Generate CRUD operations automatically
* Add authentication and authorization
* Implement business logic

### 3. **Test in Real-Time**

Use the built-in Igniter Studio to test your API as you build it - no Postman or cURL needed.

### 4. **Deploy to Production**

Learn the best practices for deploying, monitoring, and maintaining your application.

## What You'll Learn

Here's a breakdown of the skills you'll develop:

### **Core Concepts**

* Understanding Igniter.js architecture and philosophy
* Working with Controllers, Actions, and Procedures
* Managing application context and dependency injection
* Type-safe API design patterns

### **Database & Data**

* Designing schemas with Prisma
* Implementing CRUD operations
* Data validation with Zod
* Database migrations and seeding

### **Authentication & Security**

* Setting up Better Auth
* Protected routes and middleware
* Session management
* Role-based access control

### **Advanced Features**

* Caching strategies with Redis
* Background job processing with BullMQ
* AI integration for smart features
* Payment processing with Stripe
* Real-time analytics

### **DevOps & Deployment**

* Environment configuration
* CI/CD pipelines
* Monitoring and observability
* Performance optimization

## Prerequisites

Before starting this course, you should have:

* **Basic TypeScript knowledge** - Understanding of types, interfaces, and async/await
* **React fundamentals** - Components, hooks, and props
* **Node.js installed** - Version 20.0 or later ([Download](https://nodejs.org))
* **Basic terminal skills** - Running commands and navigating directories

<Callout type="info" title="New to TypeScript or React?">
  While this course assumes basic knowledge, we'll explain concepts as we go. If you need a refresher:

  * [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
  * [React Documentation](https://react.dev/learn)
</Callout>

## What You'll Need

Make sure you have these tools ready:

* **Code Editor** - VS Code recommended ([Download](https://code.visualstudio.com/))
* **Package Manager** - npm, pnpm, yarn, or bun
* **Git** - For version control ([Download](https://git-scm.com/))
* **GitHub Account** - Free ([Sign up](https://github.com))
* **Vercel Account** - Free tier is perfect ([Sign up](https://vercel.com))

<Callout type="warn" title="Optional: Local Services">
  For the full experience, you'll eventually need:

  * **PostgreSQL** - We'll show you how to use a free cloud database
  * **Redis** - We'll use Upstash (free tier available)

  Don't worry about setting these up now - we'll guide you through it when the time comes!
</Callout>

## Course Structure

This course is organized into focused, practical chapters:

* **Chapters 1-4**: Foundation - Project setup, structure, and first features
* **Chapters 5-7**: Database - Schema design, CRUD operations, and data validation
* **Chapters 8-9**: Authentication - User management and protected routes
* **Chapters 10-12**: Frontend - Building the UI with Next.js and type-safe client
* **Chapters 13-16**: Advanced Features - Analytics, caching, jobs, and AI
* **Chapters 17-19**: Production - Payments, testing, and deployment

Each chapter builds on the previous one, so we recommend following them in order for the best learning experience.

## How to Get the Most Out of This Course

1. **Code Along** - Don't just read, type the code yourself
2. **Experiment** - Try modifying the code and see what happens
3. **Take Quizzes** - Test your understanding with interactive quizzes
4. **Build Your Own** - After completing a chapter, try building a related feature on your own
5. **Ask Questions** - Join our [Discord community](https://discord.gg/igniterjs) if you get stuck

## Ready to Build?

You're about to embark on a journey that will transform you from an Igniter.js beginner to someone who can confidently build and deploy production-ready SaaS applications.

Let's get started! 🚀

<ChapterNav
  current={{
  number: 0,
  title: "Introduction"
}}
  next={{
  number: 1,
  title: "Creating Your Project",
  description: "Use the Igniter.js CLI to scaffold your new SaaS application with Next.js",
  href: "/learn/01-creating-your-project"
}}
  isCompleted={false}
/>


---


# Showcase

Projects built with Igniter.js

---

# GetFeed

> A modern feed aggregator and RSS reader built with Igniter.js, featuring real-time updates and seamless synchronization.
URL: https://igniterjs.com/showcase/getfeed

A powerful feed aggregator demonstrating Igniter.js real-time capabilities and efficient data processing.


---

# MyLink

> A link-in-bio platform built with Igniter.js, enabling users to create beautiful landing pages with multiple links.
URL: https://igniterjs.com/showcase/mylink

A link-in-bio platform showcasing Igniter.js performance and flexibility for high-traffic applications.


---

# SaaS Boilerplate

> A complete SaaS boilerplate built with Igniter.js, featuring authentication, billing, team management, and more.
URL: https://igniterjs.com/showcase/saas-boilerplate

A production-ready SaaS boilerplate showcasing Igniter.js capabilities for building scalable SaaS applications.


---


# Templates

Starter templates and examples

---

# Real-Time Chat App

> A full-featured real-time chat application built with Next.js and Prisma, showcasing Igniter.js's SSE-based real-time features for instant updates.
URL: https://igniterjs.com/templates/sample-realtime-chat

## Overview

This template provides a production-ready real-time chat application, demonstrating how to build interactive experiences with Igniter.js, Next.js, and Prisma. It's designed for developers looking to implement real-time features with end-to-end type safety.

## Features

* ✅ **Real-Time Chat**: Functional chat with instant message delivery.
* ✅ **Next.js App Router**: Utilizes the latest Next.js conventions for modern web development.
* ✅ **End-to-End Type Safety**: Ensures type consistency from frontend components to backend API with Igniter.js.
* ✅ **Feature-Based Architecture**: Organizes code by business domain for scalability and maintainability.
* ✅ **Database Ready**: Integrated with Prisma for seamless PostgreSQL database management.
* ✅ **WebSockets**: Real-time communication powered by a simple WebSocket implementation.
* ✅ **UI Components**: Includes `shadcn/ui` for a head start on building beautiful interfaces.

## Project Structure

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="app">
      <Folder name="api">
        <Folder name="[[...all]]">
          <File name="route.ts" />
        </Folder>
      </Folder>

      <File name="layout.tsx" />
    </Folder>

    <Folder name="components" />

    <Folder name="features">
      <Folder name="message">
        <Folder name="controllers" />

        <Folder name="presentation" />
      </Folder>
    </Folder>

    <Folder name="services" />

    <File name="igniter.ts" />

    <File name="igniter.client.ts" />

    <File name="igniter.router.ts" />
  </Folder>
</Files>

## Quick Start

<Steps>
  <Step>
    ### Clone the Repository

    ```bash
    git clone https://github.com/felipebarcelospro/igniter-js.git
    cd igniter-js/apps/sample-realtime-chat
    ```
  </Step>

  <Step>
    ### Install Dependencies

    <Tabs items={['bun', 'npm', 'pnpm', 'yarn']} groupId="package-manager">
      <Tab value="bun">
        ```bash
        bun install
        ```
      </Tab>

      <Tab value="npm">
        ```bash
        npm install
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm install
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn install
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Configure Environment Variables

    Create a `.env` file in the root of the project and add your database connection URL:

    ```bash
    # .env
    DATABASE_URL="postgresql://user:password@localhost:5432/mydatabase?schema=public"
    ```
  </Step>

  <Step>
    ### Run Database Migrations

    ```bash
    bun prisma db push
    ```
  </Step>

  <Step>
    ### Run the Development Server

    ```bash
    bun dev
    ```

    Your application will be available at `http://localhost:3000`.
  </Step>
</Steps>

<Callout type="info">
  Ensure you have Node.js (v18 or higher) and Bun installed, and a PostgreSQL database running.
</Callout>

## Key Features Explained

### Next.js API Route Handler

The API entry point is `src/app/api/[[...all]]/route.ts`, which uses `nextRouteHandlerAdapter` from Igniter.js to expose the API.

```typescript
// src/app/api/[[...all]]/route.ts
import { AppRouter } from '@/igniter.router'
import { nextRouteHandlerAdapter } from '@igniter-js/core/adapters'

export const { GET, POST, PUT, DELETE } = nextRouteHandlerAdapter(AppRouter)
```

### Igniter.js API Layer

Backend logic is defined using Igniter.js:

* **Initialization (`src/igniter.ts`)**: Core Igniter instance.
* **Router (`src/igniter.router.ts`)**: Defines all API controllers.
* **Controllers (`src/features/[feature]/controllers/`)**: Group related API actions (queries and mutations).

### Type-Safe Client & React Hooks

Igniter.js automatically generates a type-safe client (`src/igniter.client.ts`) for seamless interaction with your backend from both Server and Client Components.

**Server Component Usage:**

```tsx
// app/some-server-page/page.tsx
import { api } from '@/igniter.client';

export default async function SomePage() {
  const data = await api.example.health.query();
  return <div>Status: {data.status}</div>;
}
```

**Client Component Usage:**

```tsx
// components/SomeClientComponent.tsx
'use client';
import { api } from '@/igniter.client';

export function SomeClientComponent() {
  const { data, isLoading } = api.example.health.useQuery();

  if (isLoading) return <div>Loading...</div>;
  return <div>Status: {data?.status}</div>;
}
```

## Deployment

This template is designed for easy deployment to platforms like Vercel. Follow the quick start guide and then deploy your Next.js application.


---

# Bun + React Full-Stack App

> A full-stack, type-safe application with Bun and React featuring server-side rendering and unified runtime.
URL: https://igniterjs.com/templates/starter-bun-react-app

## Overview

This template provides a high-performance, full-stack application built with Bun and React, offering a unified runtime and server-side rendering. It's ideal for developers seeking speed, type safety, and a streamlined development experience.

## Features

* ✅ **Full-Stack with Bun**: A single, unified runtime for both server and front-end code.
* ✅ **Server-Side Rendering (SSR)**: Achieves fast initial page loads and improved SEO.
* ✅ **Type-Safe API**: Powered by Igniter.js, ensuring end-to-end type safety between your front-end and back-end.
* ✅ **Feature-Based Architecture**: A scalable project structure that organizes code by business domain.
* ✅ **Ready-to-Use Services**: Pre-configured examples for:
  * **Caching**: Integrated with Redis via `@igniter-js/adapter-redis`.
  * **Background Jobs**: Asynchronous task processing with BullMQ via `@igniter-js/adapter-bullmq`.
  * **Structured Logging**: Production-ready logging.
* ✅ **TailwindCSS**: A utility-first CSS framework for rapid UI development.
* ✅ **Auto-Generated API Client**: A fully-typed client that mirrors your API, providing autocomplete and compile-time error checking.

## Project Structure

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="app" />

    <Folder name="components" />

    <Folder name="features">
      <Folder name="example">
        <Folder name="controllers" />

        <Folder name="presentation" />
      </Folder>
    </Folder>

    <Folder name="lib" />

    <Folder name="services" />

    <File name="igniter.ts" />

    <File name="igniter.client.ts" />

    <File name="igniter.context.ts" />

    <File name="igniter.router.ts" />

    <File name="index.tsx" />
  </Folder>
</Files>

## Quick Start

<Steps>
  <Step>
    ### Clone the Repository

    ```bash
    git clone https://github.com/felipebarcelospro/igniter-js.git
    cd igniter-js/apps/starter-bun-react-app
    ```
  </Step>

  <Step>
    ### Install Dependencies

    <Tabs items={['bun', 'npm', 'pnpm', 'yarn']} groupId="package-manager">
      <Tab value="bun">
        ```bash
        bun install
        ```
      </Tab>

      <Tab value="npm">
        ```bash
        npm install
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm install
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn install
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Configure Environment Variables

    Create a `.env` file in the root of this starter and add your Redis connection URL:

    ```bash
    # .env
    REDIS_URL="redis://127.0.0.1:6379"
    ```
  </Step>

  <Step>
    ### Run the Development Server

    ```bash
    bun run dev
    ```

    Your application will be available at `http://localhost:3000`.
  </Step>
</Steps>

<Callout type="info">
  Ensure you have Bun (v1.0 or higher) installed and a running Redis instance.
</Callout>

## Key Features Explained

### Bun Server (`src/index.tsx`)

The `src/index.tsx` file is the main entry point, using Bun's native `serve` function. It forwards API requests to Igniter.js and serves the React application for client-side routing.

### Igniter.js API (`src/igniter.router.ts`)

Backend API logic is defined using Igniter.js:

* **Initialization (`src/igniter.ts`)**: Core Igniter instance configured with adapters for store (Redis), jobs (BullMQ), logging, and telemetry.
* **Router (`src/igniter.router.ts`)**: Defines all API controllers.
* **Controllers (`src/features/example/controllers/example.controller.ts`)**: Group related API actions (queries and mutations), demonstrating cache interaction and background job scheduling.

### React Front-End (`src/app/`)

The user interface is a standard React application, with `src/app/_app.tsx` as the root component setting up providers, including `IgniterProvider` for the API client.

### Type-Safe Client (`src/igniter.client.ts`)

Igniter.js automatically generates a type-safe client for seamless interaction with your backend from the frontend, providing full type-checking and autocompletion.

## Deployment

This template can be deployed to various platforms that support Bun applications. Follow the quick start guide to get your application running locally, then refer to Bun's deployment documentation for production environments.


---

# Bun REST API

> A high-performance REST API built with Bun runtime and Igniter.js for maximum speed and efficiency.
URL: https://igniterjs.com/templates/starter-bun-rest-api

## Overview

This template provides a robust and scalable foundation for building high-performance, type-safe REST APIs with Bun and Igniter.js. It's designed for developers who prioritize speed, efficiency, and a strongly-typed backend.

## Features

* ✅ **High-Performance API Server**: Built on Bun, one of the fastest JavaScript runtimes available.
* ✅ **Type-Safe from the Ground Up**: Powered by Igniter.js, ensuring a strongly-typed codebase that is easy to maintain and refactor.
* ✅ **Feature-Based Architecture**: A scalable project structure that organizes code by business domain, not technical layers.
* ✅ **Ready-to-Use Services**: Pre-configured examples for:
  * **Caching**: Integrated with Redis via `@igniter-js/adapter-redis`.
  * **Background Jobs**: Asynchronous task processing with BullMQ via `@igniter-js/adapter-bullmq`.
  * **Structured Logging**: Production-ready, context-aware logging.
* ✅ **Database Ready**: Comes with Prisma set up for seamless PostgreSQL database integration.
* ✅ **Auto-Generated Type-Safe Client**: Even as a REST API, you can generate a fully-typed client (`src/igniter.client.ts`) for consumption by other TypeScript services or a separate front-end application.

## Project Structure

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="features">
      <Folder name="example">
        <Folder name="controllers" />
      </Folder>
    </Folder>

    <Folder name="services" />

    <File name="igniter.ts" />

    <File name="igniter.client.ts" />

    <File name="igniter.context.ts" />

    <File name="igniter.router.ts" />

    <File name="index.ts" />
  </Folder>
</Files>

## Quick Start

<Steps>
  <Step>
    ### Clone the Repository

    ```bash
    git clone https://github.com/felipebarcelospro/igniter-js.git
    cd igniter-js/apps/starter-bun-rest-api
    ```
  </Step>

  <Step>
    ### Install Dependencies

    <Tabs items={['bun', 'npm', 'pnpm', 'yarn']} groupId="package-manager">
      <Tab value="bun">
        ```bash
        bun install
        ```
      </Tab>

      <Tab value="npm">
        ```bash
        npm install
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm install
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn install
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Configure Environment Variables

    Create a `.env` file in the root of this starter and add your database and Redis connection URLs:

    ```bash
    # .env
    DATABASE_URL="postgresql://user:password@localhost:5432/mydatabase?schema=public"
    REDIS_URL="redis://127.0.0.1:6379"
    ```
  </Step>

  <Step>
    ### Run Database Migrations

    ```bash
    bunx prisma db push
    ```
  </Step>

  <Step>
    ### Run the Development Server

    ```bash
    bun run dev
    ```

    Your API will be available at `http://localhost:3000/api/v1`.
  </Step>
</Steps>

<Callout type="info">
  Ensure you have Bun (v1.0 or higher) installed, a running Redis instance, and a PostgreSQL database.
</Callout>

## Example API Endpoints

This starter includes an `example` controller to demonstrate key features.

* **Health Check**
  ```bash
  curl http://localhost:3000/api/v1/example/
  ```

* **Cache Demonstration**
  ```bash
  # First request (live data)
  curl http://localhost:3000/api/v1/example/cache/my-key
  # Second request (cached data)
  curl http://localhost:3000/api/v1/example/cache/my-key
  ```

* **Schedule a Background Job**
  ```bash
  curl -X POST -H "Content-Type: application/json" \
    -d '{"message": "Hello from curl"}' \
    http://localhost:3000/api/v1/example/schedule-job
  ```

* **List Jobs**
  ```bash
  curl http://localhost:3000/api/v1/example/jobs
  ```

## Deployment

This template can be deployed to various platforms that support Bun applications. Follow the quick start guide to get your API running locally, then refer to Bun's deployment documentation for production environments.


---

# Deno REST API

> A secure and modern REST API built with Deno runtime and Igniter.js featuring built-in TypeScript support.
URL: https://igniterjs.com/templates/starter-deno-rest-api

## Overview

This template provides a robust and scalable foundation for building high-performance, type-safe REST APIs with Deno and Igniter.js. It's designed for developers who prioritize security, modern features, and a strongly-typed backend.

## Features

* ✅ **Modern Deno Runtime**: Built on Deno, a simple, modern, and secure runtime for JavaScript and TypeScript.
* ✅ **Type-Safe from the Ground Up**: Powered by Igniter.js, ensuring a strongly-typed codebase that is easy to maintain and refactor.
* ✅ **Feature-Based Architecture**: A scalable project structure that organizes code by business domain, not technical layers.
* ✅ **Ready-to-Use Services**: Pre-configured examples for:
  * **Caching**: Integrated with Redis via `@igniter-js/adapter-redis`.
  * **Background Jobs**: Asynchronous task processing with BullMQ via `@igniter-js/adapter-bullmq`.
  * **Structured Logging**: Production-ready, context-aware logging.
* ✅ **Database Ready**: Comes with Prisma set up for seamless PostgreSQL database integration.
* ✅ **Auto-Generated Type-Safe Client**: Even as a REST API, you can generate a fully-typed client (`src/igniter.client.ts`) for consumption by other TypeScript services or a separate front-end application.

## Project Structure

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="features">
      <Folder name="example">
        <Folder name="controllers" />
      </Folder>
    </Folder>

    <Folder name="services" />

    <File name="igniter.ts" />

    <File name="igniter.client.ts" />

    <File name="igniter.context.ts" />

    <File name="igniter.router.ts" />

    <File name="index.ts" />
  </Folder>
</Files>

## Quick Start

<Steps>
  <Step>
    ### Clone the Repository

    ```bash
    git clone https://github.com/felipebarcelospro/igniter-js.git
    cd igniter-js/apps/starter-deno-rest-api
    ```
  </Step>

  <Step>
    ### Configure Environment Variables

    Create a `.env` file in the root of this starter and add your database and Redis connection URLs:

    ```bash
    # .env
    DATABASE_URL="postgresql://user:password@localhost:5432/mydatabase?schema=public"
    REDIS_URL="redis://127.0.0.1:6379"
    ```
  </Step>

  <Step>
    ### Run Database Migrations

    This starter uses Prisma for database management. You'll need to add a task to your `deno.json` to run migrations.

    ```json
    // deno.json
    {
      "tasks": {
        "dev": "deno run --unstable-sloppy-imports --watch --allow-net --allow-env --import-map=import_map.json src/index.ts",
        "start": "deno run --unstable-sloppy-imports --allow-net --allow-env --import-map=import_map.json src/index.ts",
        "prisma:db:push": "deno run --unstable-sloppy-imports -A npm:prisma db push"
      },
      // ... rest of the file
    }
    ```

    Then, run the task:

    ```bash
    deno task prisma:db:push
    ```
  </Step>

  <Step>
    ### Run the Development Server

    ```bash
    deno task dev
    ```

    Your API will be available at `http://localhost:8000/api/v1`.
  </Step>
</Steps>

<Callout type="info">
  Ensure you have Deno (v1.x or higher) installed, a running Redis instance, and a PostgreSQL database.
</Callout>

## Example API Endpoints

This starter includes an `example` controller to demonstrate key features.

* **Health Check**
  ```bash
  curl http://localhost:8000/api/v1/example/
  ```

* **Cache Demonstration**
  ```bash
  # First request (live data)
  curl http://localhost:8000/api/v1/example/cache/my-key
  # Second request (cached data)
  curl http://localhost:8000/api/v1/example/cache/my-key
  ```

* **Schedule a Background Job**
  ```bash
  curl -X POST -H "Content-Type: application/json" \
    -d '{"message": "Hello from curl"}' \
    http://localhost:8000/api/v1/example/schedule-job
  ```

* **List Jobs**
  ```bash
  curl http://localhost:8000/api/v1/example/jobs
  ```

## Deployment

This template can be deployed to various platforms that support Deno applications. Follow the quick start guide to get your API running locally, then refer to Deno's deployment documentation for production environments.


---

# Express REST API

> A robust REST API built with Express.js and Igniter.js featuring structured logging and background jobs.
URL: https://igniterjs.com/templates/starter-express-rest-api

## Overview

This template provides a robust and scalable foundation for building high-performance, type-safe REST APIs with Express.js and Igniter.js. It leverages the battle-tested Express framework with modern features like structured logging and background jobs.

## Features

* ✅ **Battle-Tested Express Server**: Built on Express.js, the most popular web framework for Node.js.
* ✅ **Type-Safe from the Ground Up**: Powered by Igniter.js, ensuring a strongly-typed codebase that is easy to maintain and refactor.
* ✅ **Feature-Based Architecture**: A scalable project structure that organizes code by business domain, not technical layers.
* ✅ **Ready-to-Use Services**: Pre-configured examples for:
  * **Caching**: Integrated with Redis via `@igniter-js/adapter-redis`.
  * **Background Jobs**: Asynchronous task processing with BullMQ via `@igniter-js/adapter-bullmq`.
  * **Structured Logging**: Production-ready, context-aware logging.
* ✅ **Database Ready**: Comes with Prisma set up for seamless PostgreSQL database integration.
* ✅ **Seamless Integration**: Uses the `@igniter-js/core/adapters` to cleanly connect the Igniter.js router to Express.

## Project Structure

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="features">
      <Folder name="example">
        <Folder name="controllers" />
      </Folder>
    </Folder>

    <Folder name="services" />

    <File name="igniter.ts" />

    <File name="igniter.client.ts" />

    <File name="igniter.context.ts" />

    <File name="igniter.router.ts" />

    <File name="index.ts" />
  </Folder>
</Files>

## Quick Start

<Steps>
  <Step>
    ### Clone the Repository

    ```bash
    git clone https://github.com/felipebarcelospro/igniter-js.git
    cd igniter-js/apps/starter-express-rest-api
    ```
  </Step>

  <Step>
    ### Install Dependencies

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        npm install
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm install
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn install
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun install
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Configure Environment Variables

    Create a `.env` file in the root of this starter and add your database and Redis connection URLs:

    ```bash
    # .env
    DATABASE_URL="postgresql://user:password@localhost:5432/mydatabase?schema=public"
    REDIS_URL="redis://127.0.0.1:6379"
    ```
  </Step>

  <Step>
    ### Run Database Migrations

    ```bash
    npx prisma db push
    ```
  </Step>

  <Step>
    ### Run the Development Server

    ```bash
    npm run dev
    ```

    Your API will be available at `http://localhost:3000/api/v1`.
  </Step>
</Steps>

<Callout type="info">
  Ensure you have Node.js (v18 or higher), npm (or compatible package manager), a running Redis instance, and a PostgreSQL database.
</Callout>

## Example API Endpoints

This starter includes an `example` controller to demonstrate key features.

* **Health Check**
  ```bash
  curl http://localhost:3000/api/v1/example/
  ```

* **Cache Demonstration**
  ```bash
  # First request (live data)
  curl http://localhost:3000/api/v1/example/cache/my-key
  # Second request (cached data)
  curl http://localhost:3000/api/v1/example/cache/my-key
  ```

* **Schedule a Background Job**
  ```bash
  curl -X POST -H "Content-Type: application/json" \
    -d '{"message": "Hello from curl"}' \
    http://localhost:3000/api/v1/example/schedule-job
  ```

* **List Jobs**
  ```bash
  curl http://localhost:3000/api/v1/example/jobs
  ```

## Deployment

This template can be deployed to various platforms that support Node.js applications. Follow the quick start guide to get your API running locally, then refer to Express.js deployment documentation for production environments.


---

# Next.js Full-Stack App

> A full-featured application built using the latest Next.js conventions with end-to-end type safety powered by Igniter.js.
URL: https://igniterjs.com/templates/starter-nextjs

## Overview

This template provides a robust foundation for building full-stack, type-safe applications with Next.js and Igniter.js. It leverages the latest Next.js App Router conventions and integrates essential services for modern web development.

## Features

* ✅ **Next.js App Router**: Built with the latest Next.js conventions for server and client components.
* ✅ **End-to-End Type Safety**: Powered by Igniter.js, ensuring type safety from your React components to your back-end API.
* ✅ **Feature-Based Architecture**: A scalable project structure that organizes code by business domain.
* ✅ **Ready-to-Use Services**: Pre-configured examples for:
  * **Caching**: Integrated with Redis via `@igniter-js/adapter-redis`.
  * **Background Jobs**: Asynchronous task processing with BullMQ via `@igniter-js/adapter-bullmq`.
  * **Structured Logging**: Production-ready logging.
* ✅ **Database Ready**: Comes with Prisma set up for seamless PostgreSQL database integration.
* ✅ **Seamless Integration**: Uses the `nextRouteHandlerAdapter` to cleanly connect the Igniter.js router to the Next.js App Router.
* ✅ **UI Components**: Includes a set of UI components from `shadcn/ui` to get you started quickly.

## Project Structure

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="app">
      <Folder name="api">
        <Folder name="[[...all]]">
          <File name="route.ts" />
        </Folder>
      </Folder>

      <File name="layout.tsx" />
    </Folder>

    <Folder name="components" />

    <Folder name="features">
      <Folder name="example">
        <Folder name="controllers" />
      </Folder>
    </Folder>

    <Folder name="services" />

    <File name="igniter.ts" />

    <File name="igniter.client.ts" />

    <File name="igniter.router.ts" />
  </Folder>
</Files>

## Quick Start

<Steps>
  <Step>
    ### Clone the Repository

    ```bash
    git clone https://github.com/felipebarcelospro/igniter-js.git
    cd igniter-js/apps/starter-nextjs
    ```
  </Step>

  <Step>
    ### Install Dependencies

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        npm install
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm install
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn install
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun install
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Configure Environment Variables

    Create a `.env` file in the root of this starter and add your database and Redis connection URLs:

    ```bash
    # .env
    DATABASE_URL="postgresql://user:password@localhost:5432/mydatabase?schema=public"
    REDIS_URL="redis://127.0.0.1:6379"
    ```
  </Step>

  <Step>
    ### Run Database Migrations

    ```bash
    npx prisma db push
    ```
  </Step>

  <Step>
    ### Run the Development Server

    ```bash
    npm run dev
    ```

    Your application will be available at `http://localhost:3000`.
  </Step>
</Steps>

<Callout type="info">
  Ensure you have Node.js (v18 or higher), npm (or compatible package manager), a running Redis instance, and a PostgreSQL database.
</Callout>

## Key Features Explained

### Next.js API Route Handler

The API entry point is `src/app/api/[[...all]]/route.ts`, which uses `nextRouteHandlerAdapter` from Igniter.js to expose the API.

```typescript
// src/app/api/[[...all]]/route.ts
import { AppRouter } from '@/igniter.router'
import { nextRouteHandlerAdapter } from '@igniter-js/core/adapters'

export const { GET, POST, PUT, DELETE } = nextRouteHandlerAdapter(AppRouter)
```

### Igniter.js API Layer

Backend logic is defined using Igniter.js:

* **Initialization (`src/igniter.ts`)**: Core Igniter instance configured with adapters for store (Redis), jobs (BullMQ), logging, and telemetry.
* **Router (`src/igniter.router.ts`)**: Defines all API controllers.
* **Controllers (`src/features/[feature]/controllers/`)**: Group related API actions (queries and mutations).

### Type-Safe Client & React Hooks

Igniter.js automatically generates a type-safe client (`src/igniter.client.ts`) for seamless interaction with your backend from both Server and Client Components.

**Server Component Usage:**

```tsx
// app/some-server-page/page.tsx
import { api } from '@/igniter.client';

export default async function SomePage() {
  const data = await api.example.health.query();
  return <div>Status: {data.status}</div>;
}
```

**Client Component Usage:**

```tsx
// components/SomeClientComponent.tsx
'use client';
import { api } from '@/igniter.client';

export function SomeClientComponent() {
  const { data, isLoading } = api.example.health.useQuery();

  if (isLoading) return <div>Loading...</div>;
  return <div>Status: {data?.status}</div>;
}
```

## Deployment

This template is designed for easy deployment to platforms like Vercel. Follow the quick start guide and then deploy your Next.js application.


---

# TanStack Start App

> A modern full-stack application built with TanStack Start featuring type-safe routing and server functions.
URL: https://igniterjs.com/templates/starter-tanstack-start

## Overview

This template provides a modern, performant foundation for full-stack web applications using TanStack Start, Vite, and Igniter.js. It combines file-based routing with an end-to-end type-safe API layer.

## Features

* ✅ **Full-Stack with TanStack Start**: A cohesive, modern full-stack framework powered by Vite.
* ✅ **End-to-End Type Safety**: Powered by Igniter.js, ensuring type safety between your front-end and back-end.
* ✅ **File-Based Routing**: Uses TanStack Router for intuitive, type-safe routing.
* ✅ **Server-Side Data Fetching**: Leverages TanStack Router's loaders to fetch data on the server.
* ✅ **Feature-Based API Architecture**: A scalable project structure that organizes API code by business domain.
* ✅ **Ready-to-Use Services**: Pre-configured examples for:
  * **Caching**: Integrated with Redis via `@igniter-js/adapter-redis`.
  * **Background Jobs**: Asynchronous task processing with BullMQ via `@igniter-js/adapter-bullmq`.
* ✅ **Auto-Generated API Client**: A fully-typed client that mirrors your API, providing autocomplete and compile-time error checking.

## Project Structure

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="components" />

    <Folder name="features">
      <Folder name="example">
        <Folder name="controllers" />
      </Folder>
    </Folder>

    <Folder name="routes">
      <Folder name="api">
        <Folder name="v1">
          <File name="$.ts" />
        </Folder>
      </Folder>

      <File name="__root.tsx" />

      <File name="index.tsx" />
    </Folder>

    <Folder name="services" />

    <File name="igniter.ts" />

    <File name="igniter.client.ts" />

    <File name="igniter.router.ts" />

    <File name="router.tsx" />
  </Folder>
</Files>

## Quick Start

<Steps>
  <Step>
    ### Clone the Repository

    ```bash
    git clone https://github.com/felipebarcelospro/igniter-js.git
    cd igniter-js/apps/starter-tanstack-start
    ```
  </Step>

  <Step>
    ### Install Dependencies

    <Tabs items={['npm', 'pnpm', 'yarn', 'bun']} groupId="package-manager">
      <Tab value="npm">
        ```bash
        npm install
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm install
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn install
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun install
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Configure Environment Variables

    Create a `.env` file in the root of this starter and add your database and Redis connection URLs:

    ```bash
    # .env
    DATABASE_URL="postgresql://user:password@localhost:5432/mydatabase?schema=public"
    REDIS_URL="redis://127.0.0.1:6379"
    ```
  </Step>

  <Step>
    ### Run Database Migrations

    ```bash
    npx prisma db push
    ```
  </Step>

  <Step>
    ### Run the Development Server

    ```bash
    npm run dev
    ```

    Your application will be available at `http://localhost:5173`.
  </Step>
</Steps>

<Callout type="info">
  Ensure you have Node.js (v18 or higher), npm (or compatible package manager), a running Redis instance, and a PostgreSQL database.
</Callout>

## Key Features Explained

### API Integration via Catch-All Route

The connection between TanStack Start and Igniter.js is a catch-all API route at `src/routes/api/v1/$.ts`. This route captures all requests to `/api/v1/*` and delegates them to the Igniter.js API router handler.

### Igniter.js API Layer

Backend API logic is defined using Igniter.js:

* **Initialization (`src/igniter.ts`)**: Core Igniter instance configured with adapters for store (Redis), jobs (BullMQ), and logging.
* **Router (`src/igniter.router.ts`)**: Assembles the main API router by importing all feature controllers.
* **Controllers (`src/features/[feature]/controllers/`)**: Group related API actions (queries and mutations).

### Type-Safe Client & React Hooks

Igniter.js automatically generates a type-safe client (`src/igniter.client.ts`) for seamless interaction with your backend from the frontend, providing full type-checking and autocompletion.

**Example Client Component Usage:**

```tsx
// src/routes/index.tsx
'use client';
import { api } from '@/igniter.client';

export function Component() {
  const { data, isLoading } = api.example.health.useQuery();

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <h1>Welcome to TanStack Start!</h1>
      <p>API Status: {data?.status}</p>
    </div>
  );
}
```

## Deployment

This template can be deployed to various platforms that support Node.js applications. Follow the quick start guide to get your application running locally, then refer to TanStack Start's deployment documentation for production environments.


---