adk-frontend

What this skill does

# ADK Frontend Integration

Use this skill when users ask questions about building frontend applications that connect to Botpress ADK bots. This covers authentication patterns, type-safe API calls, client configuration, and integrating generated types.

## What is ADK Frontend Integration?

When you build a bot with the Botpress ADK, you often need a frontend application that interacts with it. This skill provides production-tested patterns for:

- **Authentication** - Cookie-based PAT storage with OAuth flow
- **Client Management** - Zustand store pattern for client caching and reuse
- **Type Generation** - Using ADK-generated types for full type safety
- **Action Calls** - Calling bot actions with proper error handling and optimistic updates

### Key Technologies

- **@botpress/client** - Official TypeScript client for Botpress API
- **Triple-slash references** - TypeScript pattern for importing generated types
- **React Query** - For mutations and cache management (optional but recommended)
- **Zustand** - For client state management

---

## When to Use This Skill

Activate this skill when users ask frontend-related questions like:

### Authentication Questions

- "How do I authenticate with Botpress from my frontend?"
- "What are Personal Access Tokens (PATs)?"
- "Should I use cookies or localStorage for tokens?"
- "How do I implement OAuth login flow?"
- "How do I protect routes based on authentication?"
- "How do I handle token expiration?"

### Client Setup Questions

- "How do I initialize the Botpress client?"
- "What's the best way to manage multiple client instances?"
- "Why use a client store?"
- "How do I create workspace-scoped vs bot-scoped clients?"
- "What's the difference between regular client and Zai client?"

### Type Generation Questions

- "How do I get types for my bot's actions?"
- "What are triple-slash references?"
- "How do I import generated types?"
- "Where are the .adk type files?"
- "How do I keep types in sync between bot and frontend?"
- "Why can't TypeScript find my action types?"

### Calling Actions Questions

- "How do I call a bot action from my frontend?"
- "What's the syntax for client.callAction()?"
- "How do I handle errors when calling actions?"
- "How do I implement optimistic updates?"
- "How do I chain multiple action calls?"
- "How do I use React Query with bot actions?"

---

## Available Documentation

Documentation files in `./references/`:

### Core Integration Patterns

- **authentication.md** - Complete authentication system with PATs, cookies, OAuth, route protection
- **botpress-client.md** - Client initialization, Zustand store pattern, Zai client setup
- **calling-actions.md** - Type-safe action calls, mutations, error handling, optimistic updates
- **type-generation.md** - Triple-slash references, generated types, maintaining type safety

### Architecture & Setup

- **overview.md** - Architecture overview, when to use ADK frontends, project structure
- **project-setup.md** - Vite + React scaffolding, TypeScript config, environment setup
- **recommended-stack.md** - Recommended tech stack with rationale

### Data & State Patterns

- **service-layer.md** - Service layer pattern for wrapping API calls with types
- **data-fetching.md** - TanStack Query patterns, mutations, optimistic updates
- **state-management.md** - Zustand vs TanStack Query, when to use each
- **realtime-updates.md** - Polling strategies, interval tiers, performance considerations

---

## How to Answer Frontend Questions

Frontend questions typically fall into these categories:

### 1. Authentication Implementation

When users ask about authentication, reference the complete pattern from `authentication.md`:

**Key Concepts:**

- PAT generation in Botpress Cloud
- Cookie-based storage (not localStorage)
- AuthContext with React Context API
- OAuth callback flow via cli-login
- Route protection with TanStack Router
- Profile fetching from both Botpress API and bot tables

**Response Pattern:**

1. Explain the authentication strategy (cookies vs localStorage)
2. Show the AuthProvider implementation
3. Demonstrate the OAuth flow
4. Provide route protection examples
5. Highlight security best practices

### 2. Client Setup and Management

When users ask about client configuration, reference `botpress-client.md`:

**Key Concepts:**

- Client initialization with apiUrl, workspaceId, token, botId
- Zustand store for client caching
- Dynamic client keys for reuse
- Workspace-scoped vs bot-scoped clients
- Extended timeouts for Zai operations

**Response Pattern:**

1. Show the clientsStore.ts pattern
2. Explain how client caching works
3. Demonstrate getApiClient() usage
4. Show when to use workspace vs bot-scoped clients
5. Explain getZaiClient() for AI operations

### 3. Type Generation and Import

When users ask about types, reference `type-generation.md`:

**Key Concepts:**

- ADK generates types in `.adk/` directory during dev/build
- Triple-slash directives for referencing external types
- Generated files: action-types.d.ts, table-types.d.ts, workflow-types.d.ts
- Creating type aliases for cleaner code
- Keeping types in sync with adk dev

**Response Pattern:**

1. Explain how ADK generates types
2. Show triple-slash reference syntax
3. Demonstrate importing generated types
4. Provide examples of creating type aliases
5. Show how types stay in sync automatically

### 4. Calling Bot Actions

When users ask about calling actions, reference `calling-actions.md`:

**Key Concepts:**

- client.callAction() signature
- Type-safe input/output with BotActionDefinitions
- Service layer pattern for reusable action calls
- Using useMutation for loading states and error handling
- Optimistic updates for instant UI feedback
- Chaining actions (sequential vs parallel)

**Response Pattern:**

1. Show the basic callAction() syntax
2. Demonstrate type-safe service functions
3. Provide useMutation examples
4. Show error handling patterns
5. Explain optimistic updates when relevant

---

## Common Patterns Reference

### Authentication Flow

```typescript
// 1. Cookie helpers
function setCookie(name: string, value: string, days = 365);
function getCookie(name: string): string | null;
function deleteCookie(name: string);

// 2. AuthContext
interface AuthContextType {
  token: string | null;
  isAuthenticated: boolean;
  userProfile: UserProfile | null;
  isLoadingProfile: boolean;
  login: (token: string) => void;
  logout: () => void;
}

// 3. OAuth Flow
// Redirect: https://app.botpress.cloud/cli-login?redirect=...
// Callback: /auth/callback?pat=bp_pat_...
// Store PAT in cookie and navigate to app
```

### Client Store Pattern

```typescript
// stores/clientsStore.ts
const useClientsStore = create<ClientsState>()((set, get) => ({
  APIClients: {},
  getAPIClient: (props) => {
    const key = props?.botId
      ? `${props.workspaceId}-${props.botId}`
      : (props?.workspaceId ?? DEFAULT_API_CLIENT_KEY);

    const cached = get().APIClients[key];
    if (cached) return cached;

    const newClient = new APIClient({
      apiUrl: API_BASE_URL,
      workspaceId: props?.workspaceId,
      token: getPat() ?? "",
      botId: props?.botId,
    });

    set((state) => ({
      APIClients: { ...state.APIClients, [key]: newClient },
    }));

    return newClient;
  },
}));

export const getApiClient = (props?) =>
  useClientsStore.getState().getAPIClient(props);
```

### Type Import Pattern

```typescript
// types/index.ts
/// <reference path="../../../bot/.adk/action-types.d.ts" />
/// <reference path="../../../bot/.adk/table-types.d.ts" />

import type { BotActionDefinitions } from "@botpress/runtime/_types/actions";
import type { TableDefinitions } from "@botpress/runtime/_types/tables";

// Create type aliases
export type SendMessageAction = BotActionDefinitions["sendMessage"];
export type TicketTableRow = TableDefinitions["TicketsTable"]["Output"];
```

### Action Call Pattern

```typescript
// services/bot-service.ts
export async function