npm - codicent-app-sdk - Versions diffs - 0.4.15 → 0.4.17 - Mend

codicent-app-sdk 0.4.15 → 0.4.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2257) hide show

package/README.md CHANGED Viewed

@@ -1,521 +1,556 @@
-# Codicent App SDK
-![Build Status](https://img.shields.io/github/actions/workflow/status/izaxon/codicent-app-sdk/main.yml?branch=main)
-![License](https://img.shields.io/github/license/izaxon/codicent-app-sdk)
-![Version](https://img.shields.io/badge/version-0.4.0-blue)
-**A comprehensive SDK for building AI-powered, chat-centric web applications with Codicent.**
-Codicent App SDK provides React components, hooks, and utilities to help you quickly build, customize, and deploy modern AI-powered apps. It is designed for rapid prototyping and production use, with built-in support for chat, markdown rendering, file uploads, and more.
----
-## 🚀 Quick Start (v2 - Simplified Bootstrap)
-**New in v0.4.0:** Create a complete Codicent app with a single function call!
-```tsx
-import { createCodicentApp } from 'codicent-app-sdk';
-const app = createCodicentApp({
-  name: "My CRM",
-  apiBaseUrl: "https://codicent.com/",
-  buttons: [
-    { title: "Customers", url: "./#/list?tag=customer2" },
-    { title: "Quotes", url: "./#/list?tag=offertjson" },
-    { title: "Chat", url: "./#/chat" },
-  ],
-  listDefinitions: {
-    customer2: [
-      { key: "name", title: "Name", filterable: true },
-      { key: "email", title: "Email" },
-      { key: "phone", title: "Phone" },
-    ],
-  },
-  translations: {
-    en: { "Kunder": "Customers", "Offerter": "Quotes" },
-    sv: { "Customers": "Kunder", "Quotes": "Offerter" },
-  },
-  modules: {
-    sales: true,
-    voice: true,
-    search: true,
-  },
-  chatInstructions: "You are a helpful CRM assistant.",
-});
-// Render to DOM
-app.render("#root");
-```
-That's it! You now have a fully configured Codicent vertical app with:
-- ✅ Auth0 authentication
-- ✅ Navigation buttons
-- ✅ List views with filtering and sorting
-- ✅ i18n support
-- ✅ AI chat integration
-- ✅ Module-based feature flags
----
-## Installation
-### From GitHub (Recommended)
-```bash
-npm install github:izaxon/codicent-app-sdk
-# or
-yarn add github:izaxon/codicent-app-sdk
-```
-### From npm
-```bash
-npm install codicent-app-sdk
-# or
-yarn add codicent-app-sdk
-```
----
-## Usage
-### Option 1: Simplified Bootstrap (v2 - Recommended)
-Use `createCodicentApp()` for the fastest setup. This handles all initialization, routing, and authentication automatically.
-```tsx
-import { createCodicentApp } from 'codicent-app-sdk';
-const app = createCodicentApp({
-  name: "My App",
-  apiBaseUrl: "https://codicent.com/",
-  // ... config
-});
-app.render("#root");
-```
-See the [API Reference](#api-reference) below for all configuration options.
-### Option 2: Manual Initialization (v1 - Still Supported)
-Before using the SDK, initialize it with your app’s settings:
-```tsx
-import { initCodicentApp } from 'codicent-app-sdk';
-initCodicentApp({
-  API_BASE_URL: 'https://codicent.com/',
-  APP_NAME: 'my-app',
-  // ...other config
-});
-```
-#### Configuration Options
-**Required:**
-```js
-API_BASE_URL: string // e.g. 'https://codicent.com/' or 'https://api.yourdomain.com/' (custom domains supported)
-APP_NAME: string     // e.g. 'my-app'
-APP_PREFIX: string   // e.g. 'myapp'
-USER_PREFIX: string  // e.g. 'users'
-```
-**Optional:**
-```js
-BUTTON_BORDER_RADIUS: string
-BUTTON_BACKGROUND_COLOR: string
-DEFAULT_LANGUAGE: string
-SUBSCRIPTION_NEEDED: boolean
-REALTIME_VOICE_MODEL: string // Voice model: "alloy", "shimmer", or "echo" (default: "alloy")
-USE_REALTIME_SESSION_ENDPOINT: boolean // Use secure session endpoint (default: true)
-// Compose page location options:
-COMPOSE_HIDE_LOCATION: string  // Set to "true" to hide the GPS toggle button entirely
-COMPOSE_AUTO_LOCATION: string  // Set to "true" to automatically capture GPS on compose page load
-// ...and more
-```
-#### Compose page GPS / location
-The `Compose` page (route `/new`) supports GPS location tagging. When a location is attached, a `#gps(lat,lon)` tag is appended to the message content — readable by the AI chat instructions and queryable via tag search.
-| Option | Value | Behaviour |
-|--------|-------|-----------|
-| `COMPOSE_HIDE_LOCATION` | `"true"` | Hides the GPS toggle button; users cannot attach location |
-| `COMPOSE_HIDE_LOCATION` | `"false"` (default) | Shows the GPS toggle button; users opt-in per post |
-| `COMPOSE_AUTO_LOCATION` | `"true"` | GPS is fetched **automatically** when the compose page opens — no button tap required. The toggle button is still shown so users can remove it if desired |
-Example — always capture location (e.g. a spot-logging app):
-```js
-COMPOSE_HIDE_LOCATION: "false",
-COMPOSE_AUTO_LOCATION: "true",
-```
-For AI voice configuration and security, see the [Voice Upgrade Guide](VOICE_UPGRADE_GUIDE.md).
-#### Using Custom Domains
-The SDK fully supports custom domains for self-hosted or white-label deployments. Simply configure your custom API base URL:
-```tsx
-import { initCodicentApp } from 'codicent-app-sdk';
-// Using a custom domain
-initCodicentApp({
-  API_BASE_URL: 'https://api.yourdomain.com/',  // Your custom API endpoint
-  APP_NAME: 'my-app',
-  APP_PREFIX: 'myapp',
-  USER_PREFIX: 'users',
-  // ... other config
-});
-```
-All API calls, including authentication, chat, file uploads, and data operations, will automatically route to your custom domain. Both the SDK and the underlying codicentjs library support custom base URLs.
-📄 **For complete custom domain setup, see the [Custom Domain Configuration Guide](docs/CUSTOM_DOMAIN_GUIDE.md)**
----
-## API Reference
-### `createCodicentApp(config)`
-Creates a fully-configured Codicent app instance.
-**Parameters:**
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `name` | `string` | ✅ | Application name |
-| `apiBaseUrl` | `string` | ✅ | API base URL (e.g., "https://codicent.com/") |
-| `appPrefix` | `string` | | App-specific URL prefix (defaults to kebab-cased name) |
-| `userPrefix` | `string` | | User namespace prefix (default: "users") |
-| `buttons` | `ButtonConfig[]` | | Navigation buttons |
-| `listDefinitions` | `ListDefinitions` | | List view column definitions per tag |
-| `translations` | `Translations` | | i18n translation maps by language |
-| `defaultLanguage` | `string` | | Default language code (default: "en") |
-| `modules` | `ModuleFlags` | | Feature module flags (sales, voice, forms, etc.) |
-| `chatInstructions` | `string` | | AI chat system prompt |
-| `voiceInstructions` | `string` | | AI voice system prompt |
-| `auth0` | `Auth0Config` | | Auth0 configuration |
-| `stripe` | `StripeConfig` | | Stripe configuration |
-| `theme` | `ThemeConfig` | | Theme/branding configuration |
-**Returns:** `CodicentApp` instance with:
-- `render(container)` - Render app to a DOM element
-- `unmount()` - Unmount the app
-- `getConfig()` - Get current configuration
-**Example:**
-```tsx
-const app = createCodicentApp({
-  name: "Sales CRM",
-  apiBaseUrl: "https://codicent.com/",
-  buttons: [
-    { title: "Dashboard", url: "./#/" },
-    { title: "Customers", url: "./#/list?tag=customer2" },
-  ],
-  listDefinitions: {
-    customer2: [
-      { key: "name", title: "Customer Name", filterable: true },
-      { key: "email", title: "Email" },
-    ],
-  },
-  modules: { sales: true, voice: false },
-});
-app.render("#root");
-```
----
-## TypeScript Types
-All public types are fully documented with JSDoc and exported from `codicent-app-sdk`:
-```tsx
-import type {
-  ButtonConfig,
-  ColumnDefinition,
-  ListDefinitions,
-  ModuleFlags,
-  Translations,
-  UserInfo,
-  DataMessage,
-  CodicentAppState,
-  // ... and more
-} from 'codicent-app-sdk';
-```
-See [src/types/index.ts](src/types/index.ts) for the complete type definitions.
----
-## Components
-### Standalone Components
-The SDK exports several standalone React components that can be used independently:
-#### `Chat`
-AI chat interface component (exported from pages).
-```tsx
-import { Chat } from 'codicent-app-sdk';
-<Chat />
-```
-For detailed usage, see [src/pages/Chat.tsx](src/pages/Chat.tsx).
-#### `ListView`
-Display tabular data with sorting, filtering, and actions. While ListView is currently in the `codicentapp` package, you can import the types from the SDK:
-```tsx
-import type { ColumnDefinition, ListViewProps } from 'codicent-app-sdk';
-```
-See [codicentapp/src/components/ListView.tsx](../codicentapp/src/components/ListView.tsx) for the reference implementation.
----
-### CRUD Operations
-The SDK provides comprehensive CRUD (Create, Read, Update, Delete) methods for managing structured data. For detailed documentation and examples, see:
-📄 **[CRUD Method Usage Guide](../CRUD_METHOD_USAGE.md)** - Complete guide covering:
-- CodicentService CRUD methods
-- Usage patterns for project/task management and business records
-- JavaScript library (codicentjs) API
-- Best practices and complete examples
-### Example: Simple Chat App
-```tsx
-import React from 'react';
-import { CodicentService, useChat, Markdown, initCodicentApp } from 'codicent-app-sdk';
-initCodicentApp({
-  API_BASE_URL: 'https://codicent.com/',
-  APP_NAME: 'my-app',
-  APP_PREFIX: 'myapp',
-  USER_PREFIX: 'users',
-});
-const App = () => {
-  const codicentService = new CodicentService();
-  const { messages, sendMessage } = useChat(codicentService);
-  return (
-    <div>
-      {messages.map(msg => (
-        <div key={msg.id}>
-          <Markdown content={msg.content} />
-        </div>
-      ))}
-      <button onClick={() => sendMessage('Hello world')}>Send</button>
-    </div>
-  );
-};
-```
----
-## Features
-- **React Components:** Chat UI, Markdown, File Upload, Audio, and more
-- **Hooks:** Chat state, authentication, localization, theme, and more
-- **AI Voice:** Realtime voice AI with secure session endpoint support (see [Voice Upgrade Guide](VOICE_UPGRADE_GUIDE.md))
-- **State Management:** Efficient state machine with caching capabilities (see [State Management Caching Improvements](STATE_MANAGEMENT_CACHING_IMPROVEMENTS.md))
-- **Utilities:** Helpers for app state, device, logging, and more
-- **TypeScript Support:** Full typings for all exports
-- **Customizable:** Theming and configuration options
----
-## Development
-### Building and Publishing
-The SDK uses GitHub Actions to automate the build and publishing process:
-1. On push to the main branch:
-   - The package is automatically built
-   - Documentation is deployed to GitHub Pages
-2. When a new version tag is pushed (e.g., `v0.3.12`):
-   - The package is built
-   - A GitHub Release is created with the built package
-   - The package is published to GitHub Packages
-### Release Process
-To release a new version:
-```bash
-# 1. Update version in package.json
-npm version patch|minor|major
-# 2. Push changes with tags
-git push --follow-tags
-```
-This will trigger the GitHub Actions workflow to create a release and publish the package.
-### Local Development
-For local development:
-```bash
-# Install dependencies
-npm install
-# Run in development mode with watch
-npm run dev
-# Build locally
-npm run build
-```
-The build process generates:
-- CommonJS modules in `dist/cjs`
-- ES modules in `dist/esm`
-- TypeScript definitions
-### Testing Your Changes Locally
-You can test SDK changes in your project:
-```bash
-# In the SDK directory
-npm link
-# In your project directory
-npm link codicent-app-sdk
-```
-### Documentation
-Documentation is automatically deployed to GitHub Pages as part of the workflow when changes are pushed to the main branch.
-For manual deployment:
-```bash
-# To manually build and copy artifacts to docs directory
-npm run predeploy
-# To manually deploy documentation
-npm run deploy
-```
-## Publishing to npm
-To publish this package to npm:
-1. **Login to npm** (if you haven't already):
-   ```bash
-   npm login
-   ```
-2. **Build the package**:
-   ```bash
-   npm run build
-   ```
-3. **Publish to npm**:
-   ```bash
-   npm publish --access public
-   ```
-**Notes:**
-- Make sure the `"name"` field in `package.json` is set to `codicent-app-sdk` (no scope).
-- The package name must be unique on npm.
-- If you get a permissions error, ensure you are the owner of the package name on npm.
-## Documentation
-For full documentation, visit [our docs site](https://izaxon.github.io/codicent-app-sdk/).
-### Additional Documentation
-- **[Voice Upgrade Guide](VOICE_UPGRADE_GUIDE.md)** - Complete guide for implementing and upgrading realtime voice AI features
-- **[State Management Caching Improvements](STATE_MANAGEMENT_CACHING_IMPROVEMENTS.md)** - Comprehensive analysis and strategies for optimizing state management performance through intelligent caching
-- **[Implementation Guide](IMPLEMENTATION_GUIDE.md)** - ✅ **NEW!** How to enable and use the state management caching system (now implemented!)
-## License
-MIT © Codicent Inside AB
----
-## Fast Local SDK Testing Workflow
-To quickly test changes in your local SDK with your app project, you can use npm link or a local file dependency. This avoids publishing to npm for every change.
-### Option 1: Using `npm link`
-1. **Build your SDK in watch mode (if needed):**
-   - If your SDK uses TypeScript or a bundler (like rollup), run it in watch mode so changes are rebuilt automatically.
-     ```cmd
-     npm run build -- --watch
-     ```
-     Or for TypeScript:
-     ```cmd
-     npx tsc --watch
-     ```
-2. **Link your SDK globally:**
-   In your SDK root folder:
-   ```cmd
-   npm link
-   ```
-3. **Link your SDK in your app project:**
-   In your app project folder (the one that uses the SDK):
-   ```cmd
-   npm link codicent-app-sdk
-   ```
-   (Replace `codicent-app-sdk` with the actual name in your SDK’s `package.json` if different.)
-4. **Test changes instantly:**
-   Now, when you make changes to your SDK and rebuild, your app will use the updated local version immediately—no need to publish or reinstall from npm.
-5. **Unlink when done:**
-   When you want to go back to using the npm-published version, run in your app project:
-   ```cmd
-   npm uninstall codicent-app-sdk
-   npm install codicent-app-sdk
-   ```
-### Option 2: Using a Local File Dependency
-1. In your app’s `package.json`, set the dependency to point to your local SDK folder:
-   ```json
-   "dependencies": {
-     "codicent-app-sdk": "file:../codicent-app-sdk"
-   }
-   ```
-2. Run `npm install` in your app project.
----
-## Listening to `codicent-log` Events
-You can listen for SDK log events of type `codicent-log` in your application. This is useful for debugging or integrating with your own logging system.
-```tsx
-// Listen for log events
-window.addEventListener('codicent-log', (event) => {
-  // event.detail contains the log payload
-  console.log('Codicent Log:', event.detail);
-});
-```
-- The event is dispatched as a [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) on the `window` object.
-- The `event.detail` property contains the log data (such as level, message, and context).
----
+# codicent-app-sdk
+React SDK for building AI-powered, multi-tenant white-label applications on top of the Codicent platform.
+**Current version:** 0.4.16 · **License:** MIT · **Peer deps:** React ≥16.8, Fluent UI v9, react-router-dom v6
+---
+## What it provides
+- `CodicentService` — data CRUD, chat, file upload, token management
+- React components — `Page`, `Content`, `Chat`, `ListView`, `Markdown`, `UploadFile`, and ~25 more
+- Pages — `AppFrame`, `Chat`, `Compose`, `Sales`, `Search`, `Snap`, `Login`, `Logout`, and more
+- Hooks — `useCodicentApp`, `useLocalization`, `useChat`, `useRealtimeVoiceAI`, `useAuthState`, and more
+- Global config — `initCodicentApp()` initializer consumed by all SDK components
+- Full TypeScript types
+This SDK is the primary dependency of `codicentapp/` (the modern white-label Vite app) in the monorepo. See `codicentapp/` for a complete real-world usage reference.
+---
+## Installation
+### From npm
+```bash
+npm install codicent-app-sdk
+```
+### Monorepo local dependency (recommended during development)
+In your app's `package.json`:
+```json
+"dependencies": {
+  "codicent-app-sdk": "file:../codicent-app-sdk"
+}
+```
+Then `npm install` in your app.
+### Peer dependencies
+Install these alongside the SDK:
+```bash
+npm install react react-dom react-router-dom @fluentui/react-components mermaid
+```
+---
+## Usage
+### 1. Initialize the SDK (once, at app startup)
+Call `initCodicentApp()` before rendering your React tree. It stores config globally so all SDK components and hooks can read it.
+```tsx
+// main.tsx
+import { initCodicentApp } from 'codicent-app-sdk';
+import { translations } from './services/translationService';
+import { getAppConfig } from './appconfig';
+initCodicentApp({
+  API_BASE_URL: 'https://codicent.com/',
+  APP_NAME: 'my-crm',
+  APP_PREFIX: 'mycrm',
+  USER_PREFIX: 'users',
+  APP_CONFIG: getAppConfig(),      // buttons, listDefinitions, chatInstructions
+  TRANSLATIONS: translations,      // { sv: {...}, en: {...}, ... }
+  USE_REALTIME_SESSION_ENDPOINT: true,
+});
+```
+### 2. Wrap with Auth0 and FluentProvider
+The SDK components depend on these providers being present in the React tree:
+```tsx
+// main.tsx (continued)
+import { Auth0Provider } from '@auth0/auth0-react';
+import { FluentProvider, webLightTheme } from '@fluentui/react-components';
+import { createRoot } from 'react-dom/client';
+createRoot(document.getElementById('root')!).render(
+  <Auth0Provider domain={AUTH0_DOMAIN} clientId={AUTH0_CLIENT_ID} authorizationParams={{ redirect_uri: window.location.origin }}>
+    <FluentProvider theme={webLightTheme}>
+      <App />
+    </FluentProvider>
+  </Auth0Provider>
+);
+```
+### 3. Use `useCodicentApp()` in your root App component
+```tsx
+// App.tsx
+import { useCodicentApp } from 'codicent-app-sdk';
+import { useAuth0 } from '@auth0/auth0-react';
+import { HashRouter, Routes, Route } from 'react-router-dom';
+import { Chat } from 'codicent-app-sdk';
+import { ListPage } from './pages/ListPage';
+export default function App() {
+  const auth0 = useAuth0();
+  const state = useCodicentApp({ auth0 });
+  if (!auth0.isAuthenticated) {
+    auth0.loginWithRedirect();
+    return null;
+  }
+  return (
+    <HashRouter>
+      <Routes>
+        <Route path="/chat" element={<Chat state={state} title="Chat" />} />
+        <Route path="/list" element={<ListPage state={state} />} />
+      </Routes>
+    </HashRouter>
+  );
+}
+```
+### 4. Build pages using SDK components
+```tsx
+// pages/ListPage.tsx
+import { Page, Content, ListView, useLocalization, CodicentAppState, DataMessage } from 'codicent-app-sdk';
+import { useEffect, useState } from 'react';
+import { APP_CONFIG } from '../appconfig';
+import { APP_BUTTONS } from '../constants';
+export const ListPage: React.FC<{ state: CodicentAppState }> = ({ state }) => {
+  const { service } = state;
+  const { t } = useLocalization();
+  const [data, setData] = useState<DataMessage[]>([]);
+  useEffect(() => {
+    service.readDataMessages('customer2').then(setData);
+  }, [service]);
+  const columns = APP_CONFIG.apps[APP_BUTTONS].listDefinitions['customer2'];
+  return (
+    <Page title={t('Kunder')}>
+      <Content>
+        <ListView data={data} columns={columns} />
+      </Content>
+    </Page>
+  );
+};
+```
+---
+## `initCodicentApp()` configuration options
+**Required:**
+| Key | Type | Description |
+|-----|------|-------------|
+| `API_BASE_URL` | `string` | Codicent backend URL, e.g. `"https://codicent.com/"` |
+| `APP_NAME` | `string` | Application identifier |
+**Common optional:**
+| Key | Type | Description |
+|-----|------|-------------|
+| `APP_PREFIX` | `string` | URL/namespace prefix for this app |
+| `USER_PREFIX` | `string` | User namespace prefix (default: `"users"`) |
+| `APP_CONFIG` | `AppConfig` | Per-app config: buttons, listDefinitions, chatInstructions |
+| `TRANSLATIONS` | `object` | i18n map `{ sv: {...}, en: {...} }`. Swedish strings are used as keys. |
+| `DEFAULT_LANGUAGE` | `string` | Default language code (e.g. `"sv"`, `"en"`) |
+| `USE_REALTIME_SESSION_ENDPOINT` | `boolean` | Use secure backend session token for voice AI (default: `true`) |
+| `REALTIME_VOICE_MODEL` | `string` | Voice model: `"alloy"`, `"shimmer"`, or `"echo"` (default: `"alloy"`) |
+| `SUBSCRIPTION_NEEDED` | `boolean` | Redirect to purchase page if no active subscription |
+| `BUTTON_BORDER_RADIUS` | `string` | CSS border-radius for nav buttons |
+| `BUTTON_BACKGROUND_COLOR` | `string` | Background color for nav buttons |
+**Compose page GPS options:**
+| Key | Value | Behaviour |
+|-----|-------|-----------|
+| `COMPOSE_HIDE_LOCATION` | `"true"` | Hides GPS toggle button entirely |
+| `COMPOSE_HIDE_LOCATION` | `"false"` (default) | Shows GPS toggle; users opt-in per post |
+| `COMPOSE_AUTO_LOCATION` | `"true"` | Captures GPS automatically on page open |
+When a location is attached, `#gps(lat,lon)` is appended to message content — queryable via tag search and readable by AI.
+---
+## API Reference
+### `CodicentService`
+The main service class for all data and chat operations. Access it via `state.service` from `useCodicentApp()`.
+**Data message CRUD:**
+```ts
+createDataMessage(tag: string, data: object, codicent?: string): Promise<string>
+readDataMessages(
+  tag: string,
+  search?: string,
+  codicent?: string,
+  start?: number,
+  length?: number,
+  afterTimestamp?: string,
+  beforeTimestamp?: string,
+  dataFilters?: Record<string, string>
+): Promise<DataMessage[]>
+readOneDataMessage(id: string): Promise<DataMessage | null>
+updateDataMessage(id: string, data: object, codicent?: string): Promise<string>
+deleteDataMessage(id: string, codicent?: string): Promise<string>
+getSchema(tag: string, codicent?: string): Promise<object | null>
+```
+**Chat and messages:**
+```ts
+sendMessage(message: string, parentId?: string, codicent?: string): Promise<Message>
+chat(message: string, messageId?: string, codicent?: string): Promise<Message>
+getMessages(tags: string[], codicent?: string, length?: number): Promise<Message[]>
+getMessagesFast(tags: string[], search?: string, length?: number, publicCodicent?: string, codicent?: string, start?: number): Promise<Message[]>
+```
+**Files:**
+```ts
+uploadFile(filename: string, formData: FormData): Promise<string>
+getFileInfo(fileId: string): Promise<FileInfo>
+static getImageUrl(fileId: string, width: number): string
+static getFileUrl(fileId: string, extension?: string): string
+```
+**Auth and tokens:**
+```ts
+getToken(): string
+generateApiToken(expires?: Date, forUserNickname?: string): Promise<string>
+```
+---
+### `useCodicentApp(options)`
+Core hook that bootstraps app state, authentication, and the `CodicentService` instance.
+```ts
+const state = useCodicentApp({
+  auth0: useAuth0(),       // Required: Auth0 hook result
+  toolsConfig?: object,    // Optional: custom AI tool handlers
+  authOptions?: object,    // Optional: override auth behaviour
+});
+```
+Returns `CodicentAppState`:
+```ts
+{
+  service: CodicentService;   // Use for all data/chat operations
+  context: StateContext;      // Project nickname, user info
+  auth: UseAuthState;
+  voice?: RealtimeVoice;      // Voice AI connection (when active)
+  audio: AudioRecorderState;
+  stateMachine: AppStateMachine;
+  state: string;              // Current state machine state
+  nickname: string;           // Active project nickname
+  error: string;
+  isBusy: () => boolean;
+  html: string;               // AI-generated HTML output
+  setHtml: (html: string) => void;
+}
+```
+### 5. Use `DataMessagePicker` for tagged record lookup
+```tsx
+import { DataMessagePicker } from 'codicent-app-sdk';
+<DataMessagePicker
+  service={state.service}
+  tag="customer2"
+  placeholder="Search customers"
+  primaryKey="Company Name"
+  displayKeys={["Company Name", "City"]}
+  secondaryKeys={["Customer Number", "City"]}
+  searchKeys={["Company Name", "Customer Number", "City"]}
+  onSelect={(selection) => {
+    console.log('Selected customer', selection.id, selection.data);
+  }}
+/>
+```
+The picker debounces lookups through `readDataMessages(...)`, shows compact autosuggest results, and returns the raw `DataMessage` plus a normalized selection payload.
+---
+### `useLocalization()`
+```ts
+const { t, tAsync, getLanguageInfo } = useLocalization();
+t('Kunder')                       // → "Customers" (in English)
+await tAsync('Kunder')            // → API-backed translation with fallback
+getLanguageInfo()                 // → { code: 'en', name: 'English', ... }
+```
+Swedish strings are used as keys. Pass your translation maps via `TRANSLATIONS` in `initCodicentApp()`.
+---
+### Components
+#### `Page`
+Full-screen layout wrapper with optional header and footer.
+```tsx
+<Page title="Customers" hideFooter={false} audio={state.audio} voice={state.voice}>
+  <Content>...</Content>
+</Page>
+```
+#### `Content`
+Flex content container — use inside `Page`.
+```tsx
+<Content>
+  <ListView data={data} columns={columns} />
+</Content>
+```
+#### `Chat` (page)
+Full chat UI with message history, input, typing indicators, file uploads.
+```tsx
+<Chat
+  state={state}
+  title="AI Assistant"
+  codicent="my-project"     // Optional: override which project to chat with
+  welcomeMessage="Hi!"      // Optional: shown when no messages exist
+  hideFooter={false}
+/>
+```
+#### `ListView`
+Tabular data view with sorting, filtering, and column actions.
+```tsx
+import { ListView } from 'codicent-app-sdk';
+<ListView
+  data={dataMessages}
+  columns={[
+    { key: 'name', title: 'Name', filterable: true },
+    { key: ['offer_number', 'offerNumber'], title: 'Quote #', filterable: true },
+    { key: 'grand_total', title: 'Total', format: formatNumber },
+    { key: 'pdf', title: 'PDF', type: 'file' },
+  ]}
+  onSelect={(item) => navigate(`/chat?id=${item.originalMessageId}`)}
+/>
+```
+Column definition options:
+- `key: string | string[]` — JSON field name; array = fallback chain
+- `format: (value) => string` — display transformer
+- `filterable: true` — per-column text filter
+- `type: "file"` — renders download link
+- `type: "checkbox"` — renders checkbox
+- `action` — icon button with click handler
+#### `AppFrame`
+Embeds an external URL in an iframe within the page layout.
+```tsx
+<AppFrame src="https://example.com/embed" title="External view" showFooter={true} />
+```
+#### `Markdown`
+Renders markdown content including GFM and Mermaid diagrams.
+```tsx
+<Markdown content={message.content} />
+```
+#### `UploadFile`
+File upload UI with progress.
+```tsx
+<UploadFile service={state.service} codicent="my-project" />
+```
+---
+### Hooks summary
+| Hook | Purpose |
+|------|---------|
+| `useCodicentApp()` | Core app state, service, auth |
+| `useLocalization()` | i18n translation |
+| `useChat(service)` | Chat message state and send |
+| `useRealtimeVoiceAI(options)` | Real-time voice AI connection |
+| `useAuthState(auth0)` | Auth lifecycle and token |
+| `useTheme()` | App theme/branding |
+| `useToaster()` | Toast notification helpers |
+| `useStateWithLocalStorage()` | Persistent local state |
+| `useAudioRecorder()` | Microphone recording |
+| `useTemplateVariables()` | Template string utilities |
+| `useTools()` | AI tool handler registration |
+| `useEmbeddings()` | Vector embedding operations |
+---
+## TypeScript types
+```tsx
+import type {
+  CodicentAppState,
+  ButtonConfig,
+  ColumnDefinition,
+  ListDefinitions,
+  DataMessage,
+  Message,
+} from 'codicent-app-sdk';
+```
+**`ButtonConfig`** — navigation button with optional RBAC claims:
+```ts
+{
+  title: string;
+  url: string;          // "#/list?tag=customer2", "voice:...", "mailto:...", etc.
+  claim?: string;       // Show only if user has this claim
+  notClaim?: string;    // Hide if user has this claim
+  subtitle?: string;
+  options?: ButtonConfig[];
+}
+```
+**`DataMessage`** — result from `readDataMessages()`:
+```ts
+{
+  id: string;
+  originalMessageId: string;       // Stable ID across updates — use this for references/tags
+  content: string;                 // Raw: "@project #data #tag\n{json}"
+  data: Record<string, unknown>;   // Parsed JSON payload
+  tags: string[];
+  createdAt: string;
+}
+```
+---
+## Alternative: `createCodicentApp()` factory
+For standalone deployments where you do not control the React entry point, `createCodicentApp()` wraps the full initialization (including Auth0Provider, FluentProvider, HashRouter) and renders to a DOM element:
+```tsx
+import { createCodicentApp } from 'codicent-app-sdk';
+const app = createCodicentApp({
+  name: 'My CRM',
+  apiBaseUrl: 'https://codicent.com/',
+  auth0: { domain: '...', clientId: '...' },
+  buttons: [
+    { title: 'Customers', url: './#/list?tag=customer2' },
+    { title: 'Chat', url: './#/chat' },
+  ],
+  listDefinitions: {
+    customer2: [
+      { key: 'name', title: 'Name', filterable: true },
+      { key: 'email', title: 'Email' },
+    ],
+  },
+  chatInstructions: 'You are a helpful CRM assistant.',
+  modules: { sales: true, voice: true },
+});
+app.render('#root');
+// app.unmount();
+// app.getConfig();
+```
+The `codicentapp/` reference implementation uses `initCodicentApp()` + manual React tree setup, which gives more control over routing and layout. `createCodicentApp()` is appropriate for simpler or standalone deployments.
+---
+## Local development workflow
+### Build the SDK
+```bash
+cd codicent-app-sdk
+npm install
+npm run build        # Output: dist/cjs/, dist/esm/, dist/index.d.ts
+npm run dev          # Watch mode
+```
+### Test in codicentapp (file: reference)
+In `codicentapp/package.json`:
+```json
+"codicent-app-sdk": "file:../codicent-app-sdk"
+```
+Then:
+```bash
+cd codicentapp
+npm install
+npm run build
+```
+### Test with npm link
+```bash
+# In SDK directory
+npm link
+# In your app directory
+npm link codicent-app-sdk
+```
+To restore npm version:
+```bash
+npm uninstall codicent-app-sdk
+npm install codicent-app-sdk
+```
+### Build output layout
+```
+dist/
+  cjs/        CommonJS modules
+  esm/        ES modules
+  index.d.ts  TypeScript definitions
+```
+### Release
+```bash
+npm version patch   # or minor / major
+npm run build
+npm publish --access public
+```
+---
+## Debugging
+The SDK emits `codicent-log` custom events on `window`:
+```tsx
+window.addEventListener('codicent-log', (event: CustomEvent) => {
+  console.log(event.detail);  // { level, message, context }
+});
+```
+---
+## Related
+- `codicentapp/` — primary consumer; complete reference implementation
+- `codicent-api-client/` — framework-agnostic fetch-based API client (shared with web components)
+- `codicent-components/` — zero-build Web Components library using the same Codicent API
+- [Voice Upgrade Guide](VOICE_UPGRADE_GUIDE.md) — real-time voice AI setup and security
+---
+## License
+MIT © Codicent Inside AB