Documentation

# React apps
npm install @syncagent/react @syncagent/js

# Next.js apps (server-safe helpers)
npm install @syncagent/nextjs @syncagent/js @syncagent/react

# Vue 3 apps
npm install @syncagent/vue @syncagent/js

# Angular apps
npm install @syncagent/angular @syncagent/js

# Node.js / any JS runtime
npm install @syncagent/js

import { SyncAgentChat } from "@syncagent/react";

export default function App() {
  return (
    <SyncAgentChat
      config={{
        apiKey: process.env.NEXT_PUBLIC_SYNCAGENT_KEY,
        connectionString: process.env.DATABASE_URL,
      }}
    />
  );
}

import { SyncAgentChat } from "@syncagent/react";

<SyncAgentChat
  config={{
    apiKey: "sa_your_key",
    connectionString: process.env.DATABASE_URL,
  }}
  // Appearance
  mode="floating"           // "floating" | "inline"
  position="bottom-right"   // "bottom-right" | "bottom-left"
  accentColor="#10b981"     // any hex color
  title="AI Assistant"
  subtitle="Ask about your data"
  welcomeMessage="Hi! Ask me anything about your data."
  placeholder="Ask anything..."
  // Behavior
  defaultOpen={false}
  persistKey="my-app"       // saves chat history to localStorage
  suggestions={[            // quick-start chips
    "Show all records",
    "Count total entries",
    "Show recent activity",
  ]}
/>

// Embed inside a fixed-height container
<div style={{ height: 600 }}>
  <SyncAgentChat
    config={{ apiKey: "...", connectionString: "..." }}
    mode="inline"
  />
</div>

import { SyncAgentProvider, useSyncAgent } from "@syncagent/react";

// 1. Wrap your app (or just the chat component)
export default function App() {
  return (
    <SyncAgentProvider
      config={{
        apiKey: "sa_your_key",
        connectionString: process.env.DATABASE_URL,
      }}
    >
      <MyChat />
    </SyncAgentProvider>
  );
}

// 2. Use the hook inside
function MyChat() {
  const {
    messages,    // Message[] — full conversation history
    isLoading,   // boolean — true while streaming
    error,       // Error | null
    status,      // { step, label } | null — live status
    lastData,    // ToolData | null — last DB query result
    sendMessage, // (content: string) => void
    stop,        // () => void — abort current stream
    reset,       // () => void — clear all messages
  } = useSyncAgent();

  return (
    <div>
      {status && <div>⏳ {status.label}</div>}
      {messages.map((msg, i) => (
        <div key={i} className={msg.role === "user" ? "user" : "ai"}>
          {msg.content}
        </div>
      ))}
      <button onClick={() => sendMessage("Show all users")}>Ask</button>
      <button onClick={stop}>Stop</button>
      <button onClick={reset}>Clear</button>
    </div>
  );
}

import { SyncAgentCustomerChat } from "@syncagent/react";

// Minimal setup — floating widget in bottom-right corner
export default function App() {
  return (
    <SyncAgentCustomerChat
      apiKey="sa_your_api_key"
      connectionString={process.env.NEXT_PUBLIC_DATABASE_URL!}
    />
  );
}

import { SyncAgentCustomerChat } from "@syncagent/react";
import type { GuestIdentity } from "@syncagent/react";

export function SupportWidget() {
  return (
    <SyncAgentCustomerChat
      apiKey="sa_your_api_key"
      connectionString={process.env.NEXT_PUBLIC_DATABASE_URL!}
      // Display
      mode="floating"
      position="bottom-right"
      defaultOpen={false}
      title="Support"
      subtitle="We're here to help"
      placeholder="Type your message..."
      welcomeMessage="Hi! How can we help you today?"
      // Theming
      accentColor="#6366f1"
      darkMode={false}
      // Guest form (shown when no externalUserId)
      guestForm={{
        title: "Welcome!",
        subtitle: "Tell us about yourself to get started",
        submitButtonText: "Start Chat",
        namePlaceholder: "Your name",
        emailPlaceholder: "you@company.com",
        phonePlaceholder: "+1 (555) 000-0000",
      }}
      // Real-time human agent messages
      pusherKey={process.env.NEXT_PUBLIC_PUSHER_KEY}
      pusherCluster="us2"
      // Events
      onEscalated={() => console.log("Escalated to human agent")}
      onResolved={(id) => console.log("Resolved:", id)}
      onGuestIdentified={(identity: GuestIdentity) => {
        console.log("Guest:", identity.name, identity.guestId);
      }}
      // Skip guest form for authenticated users
      externalUserId={currentUser?.id}
      // Extra metadata sent with every message
      metadata={{ page: window.location.pathname }}
    />
  );
}

<div style={{ height: 600, width: 400 }}>
  <SyncAgentCustomerChat
    apiKey="sa_your_api_key"
    connectionString={process.env.NEXT_PUBLIC_DATABASE_URL!}
    mode="inline"
    darkMode
    accentColor="#8b5cf6"
  />
</div>

import { SyncAgentClient } from "@syncagent/js";

const agent = new SyncAgentClient({
  apiKey: "sa_your_key",
  connectionString: process.env.DATABASE_U
});

// Non-streaming — await full response
const result = await agent.chat([
  { role: "user", content: "How many users signed up this month?" }
]);
console.log(result.text);

// Streaming — token by token
await agent.chat(
  [{ role: "user", content: "Show me the top 10 customers by revenue" }],
  {
    onToken: (token) => process.stdout.write(token),
    onComplete: (text) => console.log("\nDone"),
    onError: (err) => console.error(err),
  }
);

// Schema discovery
const schema = await agent.getSchema();
console.log(schema); // CollectionSchema[]

const history = [];

// Turn 1
history.push({ role: "user", content: "Show top 5 customers" });
const r1 = await agent.chat(history);
history.push({ role: "assistant", content: r1.text });

// Turn 2 — agent remembers context
history.push({ role: "user", content: "Now show their total orders" });
const r2 = await agent.chat(history);

await agent.chat(messages, {
  onStatus: (step, label) => {
    // step: "connecting" | "schema" | "thinking" | "querying" | "done"
    console.log(`[${step}] ${label}`);
    // [connecting] Connecting to database...
    // [querying] Querying users...
    // [thinking] Thinking...
  },
  onToken: (token) => process.stdout.write(token),
});

await agent.chat(messages, {
  onData: (data) => {
    // Called whenever a DB tool returns data
    console.log(data.collection); // "orders"
    console.log(data.data);       // array of result rows
    console.log(data.count);      // number of results

    // Update your own UI
    if (data.collection === "orders") {
      setOrders(data.data);
    }
  },
});

const controller = new AbortController();

// Start streaming
agent.chat(messages, {
  signal: controller.signal,
  onToken: (t) => process.stdout.write(t),
});

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

import express from "express";
import { SyncAgentClient } from "@syncagent/js";

const app = express();
app.use(express.json());

const agent = new SyncAgentClient({
  apiKey: process.env.SYNCAGENT_KEY,
  connectionString: process.env.DATABASE_URL,
});

// Streaming endpoint
app.post("/chat", async (req, res) => {
  res.setHeader("Content-Type", "text/plain");
  res.setHeader("Transfer-Encoding", "chunked");

  await agent.chat(req.body.messages, {
    onToken: (token) => res.write(token),
    onComplete: () => res.end(),
    onError: (err) => { res.status(500).end(err.message); },
  });
});

app.listen(3000);

import { SyncAgentClient } from "@syncagent/js";

// 1. Initialize client in customer mode
const client = new SyncAgentClient({
  apiKey: "sa_your_api_key",
  externalUserId: "customer_123", // from your auth session
});

// 2. Send a message through the support pipeline
const result = await client.customerChat("How do I reset my password?");
console.log(result.response);       // AI-generated answer
console.log(result.conversationId); // "conv_abc123"
console.log(result.escalated);      // false — handled by AI
console.log(result.resolved);       // false — conversation ongoing

// 3. Continue the conversation
const followUp = await client.customerChat("That didn't work", {
  conversationId: result.conversationId,
  onEscalated: () => {
    console.log("Escalated to human agent");
  },
  onResolved: (conversationId) => {
    console.log("Resolved:", conversationId);
  },
});

// 4. Rate after resolution
if (followUp.resolved) {
  await client.rateConversation(followUp.conversationId, 5);
}

import {
  SyncAgentClient,
  validateGuestForm,
  generateGuestIdentifier,
} from "@syncagent/js";

const client = new SyncAgentClient({
  apiKey: "sa_your_api_key",
  customerMode: true, // no externalUserId — guest mode
});

// Validate guest form data
const validation = validateGuestForm({
  name: "Jane Doe",
  email: "jane@example.com",
});

if (validation.valid) {
  // Set guest identity — persists to localStorage
  client.setGuestIdentity({
    name: "Jane Doe",
    email: "jane@example.com",
    phone: null,
    guestId: generateGuestIdentifier("jane@example.com"),
  });

  // Now customerChat() works
  const result = await client.customerChat("I need help with my order");
  console.log(result.response);
}

import { computeTheme, type ThemeColors } from "@syncagent/js";

// Generate a full color palette from an accent color
const theme: ThemeColors = computeTheme("#6366f1", false); // light mode
const darkTheme: ThemeColors = computeTheme("#6366f1", true); // dark mode

// Apply to your custom UI
console.log(theme.background);       // "#ffffff"
console.log(theme.text);             // "#111827" (4.5:1 contrast guaranteed)
console.log(theme.accent);           // "#6366f1" (3:1 contrast guaranteed)
console.log(theme.userBubble);       // accent-derived bubble color
console.log(theme.userBubbleText);   // white or black (4.5:1 guaranteed)

// app/dashboard/page.tsx — Server Component (no "use client")
import { createServerConfig } from "@syncagent/nextjs/server";
import { SyncAgentChat } from "@syncagent/nextjs";
import { getServerSession } from "next-auth";

export default async function DashboardPage() {
  const session = await getServerSession();

  const config = createServerConfig({
    apiKey: process.env.SYNCAGENT_KEY!,
    connectionString: process.env.DATABASE_URL!,
    filter: { organizationId: session.user.orgId },
    operations: session.user.isAdmin
      ? ["read", "create", "update", "delete"]
      : ["read"],
    // All new options work here too:
    systemInstruction: "You are a helpful assistant for our platform.",
    language: "English",
    confirmWrites: true,
    maxResults: 25,
    sensitiveFields: ["ssn", "salary"],
  });

  return (
    <SyncAgentChat
      config={config}
      persistKey={session.user.id}
      accentColor="#6366f1"
      context={{ userId: session.user.id, page: "dashboard" }}
    />
  );
}

import { createServerConfigFromEnv } from "@syncagent/nextjs/server";

// Reads SYNCAGENT_KEY and DATABASE_URL automatically
const config = createServerConfigFromEnv({
  filter: { orgId: session.user.orgId },
  language: "French",
});

# .env.local
SYNCAGENT_KEY=sa_your_api_key
DATABASE_URL=mongodb+srv://user:pass@cluster/db

// app/dashboard/page.tsx — Server Component
import { createServerConfig } from "@syncagent/nextjs/server";
import { ChatWithTools } from "./chat-with-tools";

export default async function Page() {
  const config = createServerConfig({
    apiKey: process.env.SYNCAGENT_KEY!,
    toolsOnly: true,
    systemInstruction: "You are a product search assistant.",
  });
  return <ChatWithTools serverConfig={config} />;
}

// app/dashboard/chat-with-tools.tsx — "use client"
import { SyncAgentChat } from "@syncagent/nextjs";

export function ChatWithTools({ serverConfig }) {
  return (
    <SyncAgentChat
      config={{
        ...serverConfig,
        tools: {
          searchProducts: {
            description: "Search products",
            inputSchema: { query: { type: "string" } },
            execute: async ({ query }) => {
              const res = await fetch(`/api/products?q=${query}`);
              return res.json();
            },
          },
        },
      }}
    />
  );
}

// app/components/chat.tsx — "use client"
import { SyncAgentChat } from "@syncagent/nextjs";

export function Chat({ serverConfig }) {
  return (
    <SyncAgentChat
      config={{
        ...serverConfig,
        onBeforeToolCall: (name, args) => {
          console.log(`[Audit] ${name}`, args);
          return true;
        },
      }}
    />
  );
}

// app/support/page.tsx — Server Component
import { createCustomerServerConfig } from "@syncagent/nextjs/server";
import { getServerSession } from "next-auth";
import { CustomerChat } from "./customer-chat";

export default async function SupportPage() {
  const session = await getServerSession();

  // Create config on the server — secrets never reach the browser
  const config = createCustomerServerConfig({
    apiKey: process.env.SYNCAGENT_KEY!,
    connectionString: process.env.SYNCAGENT_CONNECTION_STRING!,
    externalUserId: session.user.id,
    filter: { organizationId: session.user.orgId },
  });

  return <CustomerChat config={config} />;
}

// app/support/customer-chat.tsx — Client Component
"use client";

import { SyncAgentCustomerChat } from "@syncagent/nextjs";
import type { SyncAgentConfig, GuestIdentity } from "@syncagent/nextjs";

interface Props {
  config: SyncAgentConfig;
}

export function CustomerChat({ config }: Props) {
  return (
    <SyncAgentCustomerChat
      config={config}
      // Display
      mode="floating"
      position="bottom-right"
      title="Support"
      subtitle="We're here to help"
      placeholder="Ask us anything..."
      welcomeMessage="Hi! How can we help you today?"
      // Theming
      accentColor="#6366f1"
      darkMode={false}
      // Real-time (optional)
      pusherKey={process.env.NEXT_PUBLIC_PUSHER_KEY}
      pusherCluster="us2"
      // Events
      onEscalated={() => console.log("Escalated")}
      onResolved={(id) => console.log("Resolved:", id)}
      onGuestIdentified={(identity: GuestIdentity) => {
        console.log("Guest:", identity.guestId);
      }}
    />
  );
}

// app/support/page.tsx — Server Component
import { createServerConfigFromEnv } from "@syncagent/nextjs/server";
import { CustomerChat } from "./customer-chat";

export default async function SupportPage() {
  // Reads SYNCAGENT_KEY and DATABASE_URL from env automatically
  const config = createServerConfigFromEnv({
    customerMode: true,
    externalUserId: "user_123",
  });

  return <CustomerChat config={config} />;
}

# .env.local
SYNCAGENT_KEY=sa_your_api_key
SYNCAGENT_CONNECTION_STRING=mongodb+srv://user:pass@cluster/db
NEXT_PUBLIC_PUSHER_KEY=your_pusher_key  # optional — for real-time agent messages

<script setup lang="ts">
import { ref } from "vue";
import { SyncAgentClient } from "@syncagent/js";
import { useSyncAgent } from "@syncagent/vue";

const client = new SyncAgentClient({
  apiKey: import.meta.env.VITE_SYNCAGENT_KEY,
  connectionString: import.meta.env.VITE_DATABASE_URL,
});

const { messages, isLoading, error, status, sendMessage, stop, reset } = useSyncAgent({ client });
const input = ref("");

function send() {
  if (!input.value.trim()) return;
  sendMessage(input.value);
  input.value = "";
}
</script>

<template>
  <div>
    <div v-if="status">⏳ {{ status.label }}</div>
    <div v-for="(msg, i) in messages" :key="i" :class="msg.role">
      {{ msg.content }}
    </div>
    <div v-if="error">⚠️ {{ error.message }}</div>
    <input v-model="input" @keydown.enter="send" :disabled="isLoading" />
    <button @click="send" :disabled="isLoading">Send</button>
    <button v-if="isLoading" @click="stop">Stop</button>
    <button @click="reset">Clear</button>
  </div>
</template>

<script setup lang="ts">
import { computed } from "vue";
import { SyncAgentClient } from "@syncagent/js";
import { useSyncAgent } from "@syncagent/vue";
import { useAuth } from "@/composables/auth";

const { user } = useAuth();

const client = computed(() => new SyncAgentClient({
  apiKey: import.meta.env.VITE_SYNCAGENT_KEY,
  connectionString: import.meta.env.VITE_DATABASE_URL,
  filter: { organizationId: user.value.orgId },
  operations: user.value.isAdmin ? ["read","create","update","delete"] : ["read"],
}));

const { messages, sendMessage } = useSyncAgent({
  client: client.value,
  context: { userId: user.value.id },
});
</script>

<script setup lang="ts">
import { SyncAgentCustomerChat } from "@syncagent/vue";
import type { GuestIdentity } from "@syncagent/vue";

function onEscalated() {
  console.log("Conversation escalated to a human agent");
}

function onResolved(conversationId: string) {
  console.log("Conversation resolved:", conversationId);
}

function onGuestIdentified(identity: GuestIdentity) {
  console.log("Guest identified:", identity.name, identity.guestId);
}
</script>

<template>
  <SyncAgentCustomerChat
    api-key="sa_your_api_key"
    connection-string="your_connection_string"
    mode="floating"
    position="bottom-right"
    :default-open="false"
    title="Support"
    subtitle="We're here to help"
    placeholder="Type your message..."
    welcome-message="Hi! How can we help you today?"
    accent-color="#6366f1"
    :dark-mode="false"
    pusher-key="your_pusher_key"
    pusher-cluster="us2"
    @escalated="onEscalated"
    @resolved="onResolved"
    @guest-identified="onGuestIdentified"
  />
</template>

<template>
  <div style="height: 600px; width: 400px;">
    <SyncAgentCustomerChat
      api-key="sa_your_api_key"
      connection-string="your_connection_string"
      mode="inline"
      :dark-mode="true"
      accent-color="#8b5cf6"
    />
  </div>
</template>

<template>
  <SyncAgentCustomerChat
    api-key="sa_your_api_key"
    connection-string="your_connection_string"
    :external-user-id="currentUser.id"
  />
</template>

<script setup lang="ts">
import { SyncAgentCustomerChat } from "@syncagent/vue";

const guestFormConfig = {
  title: "Welcome!",
  subtitle: "Tell us about yourself to get started",
  submitButtonText: "Start Chat",
  namePlaceholder: "Your name",
  emailPlaceholder: "you@company.com",
  phonePlaceholder: "+1 (555) 000-0000",
};
</script>

<template>
  <SyncAgentCustomerChat
    api-key="sa_your_api_key"
    connection-string="your_connection_string"
    :guest-form="guestFormConfig"
  />
</template>

// app.component.ts
import { Component, OnInit } from "@angular/core";
import { SyncAgentService } from "@syncagent/angular";
import { environment } from "./environments/environment";

@Component({
  selector: "app-root",
  providers: [SyncAgentService],
  template: `
    <div *ngIf="agent.status() as s">⏳ {{ s.label }}</div>
    <div *ngFor="let msg of agent.messages()" [class]="msg.role">
      {{ msg.content }}
    </div>
    <div *ngIf="agent.error() as err">
      ⚠️ {{ err.message }}
    </div>
    <input [(ngModel)]="input" (keydown.enter)="send()" [disabled]="agent.isLoading()" />
    <button (click)="send()" [disabled]="agent.isLoading()">Send</button>
    <button *ngIf="agent.isLoading()" (click)="agent.stop()">Stop</button>
    <button (click)="agent.reset()">Clear</button>
  `,
})
export class AppComponent implements OnInit {
  input = "";
  constructor(public agent: SyncAgentService) {}

  ngOnInit() {
    this.agent.configure({
      apiKey: environment.syncagentKey,
      connectionString: environment.databaseUrl,
    });
  }

  send() {
    if (!this.input.trim()) return;
    this.agent.sendMessage(this.input);
    this.input = "";
  }
}

ngOnInit() {
  const user = this.authService.currentUser;
  this.agent.configure({
    apiKey: environment.syncagentKey,
    connectionString: environment.databaseUrl,
    filter: { organizationId: user.orgId },
    operations: user.isAdmin
      ? ["read", "create", "update", "delete"]
      : ["read"],
    context: { userId: user.id, userRole: user.role },
  });
}

// Subscribe to messages stream
this.agent.messages$
  .pipe(takeUntil(this.destroy$))
  .subscribe(messages => console.log(messages.length));

// Subscribe to each new assistant message
this.agent.message$
  .pipe(takeUntil(this.destroy$))
  .subscribe(msg => console.log(msg.content));

// Subscribe to status
this.agent.status$
  .pipe(takeUntil(this.destroy$), filter(Boolean))
  .subscribe(({ step, label }) => console.log(`[${step}] ${label}`));

import { Component } from "@angular/core";
import { SyncAgentCustomerChatComponent } from "@syncagent/angular";
import type { GuestIdentity } from "@syncagent/angular";

@Component({
  selector: "app-support",
  standalone: true,
  imports: [SyncAgentCustomerChatComponent],
  template: `
    <syncagent-customer-chat
      [apiKey]="apiKey"
      [connectionString]="connectionString"
      mode="floating"
      position="bottom-right"
      [defaultOpen]="false"
      title="Support"
      subtitle="We're here to help"
      placeholder="Type your message..."
      welcomeMessage="Hi! How can we help you today?"
      accentColor="#6366f1"
      [darkMode]="false"
      [pusherKey]="pusherKey"
      pusherCluster="us2"
      [externalUserId]="currentUser?.id"
      [metadata]="{ page: currentRoute }"
      [guestForm]="guestFormConfig"
      (escalated)="onEscalated()"
      (resolved)="onResolved($event)"
      (guestIdentified)="onGuestIdentified($event)"
    />
  `,
})
export class SupportComponent {
  apiKey = "sa_your_api_key";
  connectionString = "your_connection_string";
  pusherKey = "your_pusher_key"; // optional
  currentUser = { id: "user_123" }; // from your auth service
  currentRoute = "/support";

  guestFormConfig = {
    title: "Welcome!",
    subtitle: "Tell us about yourself to get started",
    submitButtonText: "Start Chat",
    namePlaceholder: "Your name",
    emailPlaceholder: "you@company.com",
    phonePlaceholder: "+1 (555) 000-0000",
  };

  onEscalated() {
    console.log("Conversation escalated to a human agent");
  }

  onResolved(conversationId: string) {
    console.log("Conversation resolved:", conversationId);
  }

  onGuestIdentified(identity: GuestIdentity) {
    console.log("Guest identified:", identity.name, identity.guestId);
  }
}

@Component({
  imports: [SyncAgentCustomerChatComponent],
  template: `
    <div style="height: 600px; width: 400px;">
      <syncagent-customer-chat
        [apiKey]="apiKey"
        [connectionString]="connectionString"
        mode="inline"
        [darkMode]="true"
        accentColor="#8b5cf6"
      />
    </div>
  `,
})
export class InlineChatComponent {
  apiKey = "sa_your_api_key";
  connectionString = "your_connection_string";
}

import { SyncAgentClient } from "@syncagent/js";

const client = new SyncAgentClient({
  apiKey: "sa_your_key",
  externalUserId: "customer_123", // from your auth session
});

// Send a customer support message
const result = await client.customerChat("How do I reset my password?");

console.log(result.response);       // AI-generated answer
console.log(result.escalated);      // false — handled by AI
console.log(result.conversationId); // "conv_abc123"

import { SyncAgentProvider, useCustomerChat } from "@syncagent/react";
import { SyncAgentClient } from "@syncagent/js";

const client = new SyncAgentClient({
  apiKey: "sa_your_key",
  externalUserId: "customer_123",
});

function SupportChat() {
  const {
    messages,
    conversationId,
    isLoading,
    isEscalated,
    isResolved,
    error,
    welcomeMessage,
    sendMessage,
    rateConversation,
    reset,
  } = useCustomerChat({
    onEscalated: () => console.log("Escalated to human agent"),
    onResolved: (id) => console.log("Resolved:", id),
  });

  return (
    <div>
      {welcomeMessage && <p>{welcomeMessage}</p>}
      {messages.map((msg, i) => (
        <div key={i} className={msg.role}>{msg.content}</div>
      ))}
      {isEscalated && <p>A human agent will be with you shortly.</p>}
      {isResolved && (
        <button onClick={() => rateConversation(5)}>Rate ⭐</button>
      )}
      <button onClick={() => sendMessage("Help me!")} disabled={isLoading}>
        Send
      </button>
    </div>
  );
}

export default function App() {
  return (
    <SyncAgentProvider config={{ apiKey: "sa_your_key", externalUserId: "customer_123" }}>
      <SupportChat />
    </SyncAgentProvider>
  );
}

<script setup lang="ts">
import { ref } from "vue";
import { SyncAgentClient } from "@syncagent/js";
import { useCustomerChat } from "@syncagent/vue";

const client = new SyncAgentClient({
  apiKey: import.meta.env.VITE_SYNCAGENT_KEY,
  externalUserId: "customer_123",
});

const {
  messages,        // Ref<Message[]>
  conversationId,  // Ref<string | null>
  isLoading,       // Ref<boolean>
  isEscalated,     // Ref<boolean>
  isResolved,      // Ref<boolean>
  error,           // Ref<Error | null>
  welcomeMessage,  // Ref<string | null>
  sendMessage,
  rateConversation,
  reset,
} = useCustomerChat({
  client,
  onEscalated: () => console.log("Escalated to human agent"),
  onResolved: (id) => console.log("Resolved:", id),
});

const input = ref("");

function send() {
  if (!input.value.trim()) return;
  sendMessage(input.value);
  input.value = "";
}
</script>

<template>
  <div>
    <p v-if="welcomeMessage">{{ welcomeMessage }}</p>
    <div v-for="(msg, i) in messages" :key="i" :class="msg.role">
      {{ msg.content }}
    </div>
    <p v-if="isEscalated">A human agent will be with you shortly.</p>
    <div v-if="isResolved">
      <button @click="rateConversation(5)">Rate ⭐</button>
    </div>
    <input v-model="input" @keydown.enter="send" :disabled="isLoading" />
    <button @click="send" :disabled="isLoading">Send</button>
    <button @click="reset">Clear</button>
  </div>
</template>

import { Component, OnInit } from "@angular/core";
import { CustomerChatService } from "@syncagent/angular";
import { environment } from "./environments/environment";

@Component({
  selector: "app-support-chat",
  providers: [CustomerChatService],
  template: `
    <p *ngIf="chat.welcomeMessage()">{{ chat.welcomeMessage() }}</p>
    <div *ngFor="let msg of chat.messages()" [class]="msg.role">
      {{ msg.content }}
    </div>
    <p *ngIf="chat.isEscalated()">A human agent will be with you shortly.</p>
    <div *ngIf="chat.isResolved()">
      <button (click)="rate(5)">Rate ⭐</button>
    </div>
    <input [(ngModel)]="input" (keydown.enter)="send()" [disabled]="chat.isLoading()" />
    <button (click)="send()" [disabled]="chat.isLoading()">Send</button>
  `,
})
export class SupportChatComponent implements OnInit {
  input = "";
  constructor(public chat: CustomerChatService) {}

  ngOnInit() {
    this.chat.configure({
      apiKey: environment.syncagentKey,
      connectionString: environment.databaseUrl,
      externalUserId: "customer_123", // from your auth service
      onEscalated: () => console.log("Escalated"),
      onResolved: (id) => console.log("Resolved:", id),
    });
  }

  send() {
    if (!this.input.trim()) return;
    this.chat.sendMessage(this.input);
    this.input = "";
  }

  rate(value: number) {
    this.chat.rateConversation(value);
  }
}

// app/support/page.tsx — Server Component
import { createCustomerServerConfig } from "@syncagent/nextjs/server";
import { getServerSession } from "next-auth";
import { CustomerWidget } from "./customer-widget";

export default async function SupportPage() {
  const session = await getServerSession();

  const config = createCustomerServerConfig({
    apiKey: process.env.SYNCAGENT_KEY!,
    connectionString: process.env.DATABASE_URL!,
    externalUserId: session.user.id, // required — throws if omitted
    filter: { organizationId: session.user.orgId },
  });

  return <CustomerWidget config={config} />;
}

// app/support/customer-widget.tsx — "use client"
"use client";
import { useCustomerChat } from "@syncagent/nextjs"; // re-exported from @syncagent/react
import { SyncAgentClient } from "@syncagent/js";

export function CustomerWidget({ config }: { config: any }) {
  const client = new SyncAgentClient(config);
  const { messages, sendMessage, isEscalated, rateConversation } = useCustomerChat({ client });

  return (
    <div>
      {messages.map((msg, i) => (
        <div key={i} className={msg.role}>{msg.content}</div>
      ))}
      {isEscalated && <p>Connecting you to a human agent...</p>}
      <button onClick={() => sendMessage("I need help")}>Send</button>
    </div>
  );
}

// Rate a resolved conversation (1 = poor, 5 = excellent)
await client.rateConversation(result.conversationId, 5);

// Validation rules:
// - conversationId is required (throws if empty)
// - rating must be an integer between 1 and 5 (throws otherwise)

const result = await client.customerChat("I need to cancel my subscription", {
  conversationId: "conv_abc123",
  onEscalated: () => {
    // Show a banner: "Connecting you to a human agent..."
    showBanner("A support agent will be with you shortly.");
  },
  onResolved: (conversationId) => {
    // Prompt the user to rate the conversation
    showRatingDialog(conversationId);
  },
});

npm install @syncagent/react @syncagent/js

import { SyncAgentClient } from "@syncagent/js";

const client = new SyncAgentClient({
  apiKey: "sa_your_key",
  externalUserId: currentUser.id, // from your auth session
});

import { useState } from "react";
import { SyncAgentClient } from "@syncagent/js";
import { SyncAgentProvider, useCustomerChat } from "@syncagent/react";

// Configure the client
const client = new SyncAgentClient({
  apiKey: process.env.NEXT_PUBLIC_SYNCAGENT_KEY!,
  externalUserId: "user_123", // replace with authenticated user ID
});

function CustomerSupportChat() {
  const {
    messages,
    isLoading,
    isEscalated,
    isResolved,
    welcomeMessage,
    sendMessage,
    rateConversation,
    reset,
  } = useCustomerChat({
    onEscalated: () => {
      // Notify the user that a human agent is taking over
    },
    onResolved: (conversationId) => {
      // Prompt the user to rate the conversation
    },
  });

  const [input, setInput] = useState("");

  const handleSend = () => {
    if (!input.trim()) return;
    sendMessage(input);
    setInput("");
  };

  return (
    <div className="chat-container">
      {/* Escalation banner */}
      {isEscalated && (
        <div className="escalation-banner">
          🙋 A human agent is reviewing your conversation.
        </div>
      )}

      {/* Welcome message */}
      {welcomeMessage && (
        <div className="welcome">{welcomeMessage}</div>
      )}

      {/* Messages */}
      {messages.map((msg, i) => (
        <div key={i} className={msg.role === "user" ? "user-msg" : "agent-msg"}>
          {msg.content}
        </div>
      ))}

      {isLoading && <div className="typing-indicator">Agent is typing...</div>}

      {/* Rating prompt after resolution */}
      {isResolved && (
        <div className="rating-prompt">
          <p>How was your experience?</p>
          {[1, 2, 3, 4, 5].map((star) => (
            <button key={star} onClick={() => rateConversation(star)}>
              {"⭐".repeat(star)}
            </button>
          ))}
        </div>
      )}

      {/* Input */}
      <div className="input-row">
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          onKeyDown={(e) => e.key === "Enter" && handleSend()}
          placeholder="Type your message..."
          disabled={isLoading}
        />
        <button onClick={handleSend} disabled={isLoading}>Send</button>
      </div>

      <button onClick={reset}>New Conversation</button>
    </div>
  );
}

// Wrap with provider
export default function App() {
  return (
    <SyncAgentProvider config={{ apiKey: process.env.NEXT_PUBLIC_SYNCAGENT_KEY!, externalUserId: "user_123" }}>
      <CustomerSupportChat />
    </SyncAgentProvider>
  );
}

// Rate after resolution
await rateConversation(5); // 1-5 scale

import { SyncAgentClient } from "@syncagent/js";

const { db, support } = SyncAgentClient.createDual({
  apiKey: "sa_your_key",
  connectionString: "postgresql://user:pass@host:5432/mydb",
  externalUserId: currentUser.id, // from your auth session
});

// Admin: direct database queries
const result = await db.chat([
  { role: "user", content: "Show all overdue invoices" }
]);

// Customer: support pipeline (persona, flows, KB, escalation)
const reply = await support.customerChat("I need help with my order");
await support.rateConversation(reply.conversationId, 5);

import { useState } from "react";
import { SyncAgentClient } from "@syncagent/js";
import { SyncAgentProvider, useSyncAgent, useCustomerChat } from "@syncagent/react";

// Create both clients from a single config
const { db, support } = SyncAgentClient.createDual({
  apiKey: process.env.NEXT_PUBLIC_SYNCAGENT_KEY!,
  connectionString: process.env.NEXT_PUBLIC_DATABASE_URL!,
  externalUserId: "user_123", // from your auth session
  filter: { organizationId: "org_456" }, // multi-tenant scoping
});

// --- Admin Panel (Database Agent) ---
function AdminPanel() {
  const { messages, sendMessage, isLoading } = useSyncAgent({ client: db });
  const [input, setInput] = useState("");

  return (
    <div className="admin-panel">
      <h2>Admin Dashboard</h2>
      {messages.map((msg, i) => (
        <div key={i} className={msg.role}>{msg.content}</div>
      ))}
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        onKeyDown={(e) => {
          if (e.key === "Enter" && input.trim()) {
            sendMessage(input);
            setInput("");
          }
        }}
        placeholder="Query your database..."
        disabled={isLoading}
      />
    </div>
  );
}

// --- Customer Support Widget (Customer Agent) ---
function CustomerWidget() {
  const {
    messages,
    sendMessage,
    isLoading,
    isEscalated,
    isResolved,
    welcomeMessage,
    rateConversation,
  } = useCustomerChat({
    client: support,
    onEscalated: () => console.log("Escalated to human agent"),
    onResolved: (id) => console.log("Resolved:", id),
  });
  const [input, setInput] = useState("");

  return (
    <div className="customer-widget">
      <h2>Need Help?</h2>
      {welcomeMessage && <p className="welcome">{welcomeMessage}</p>}
      {messages.map((msg, i) => (
        <div key={i} className={msg.role}>{msg.content}</div>
      ))}
      {isEscalated && <p>🙋 A human agent will be with you shortly.</p>}
      {isResolved && (
        <div>
          <p>✅ Resolved! How was your experience?</p>
          {[1, 2, 3, 4, 5].map((r) => (
            <button key={r} onClick={() => rateConversation(r)}>{"⭐".repeat(r)}</button>
          ))}
        </div>
      )}
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        onKeyDown={(e) => {
          if (e.key === "Enter" && input.trim()) {
            sendMessage(input);
            setInput("");
          }
        }}
        placeholder="Ask a question..."
        disabled={isLoading}
      />
    </div>
  );
}

// --- App Layout ---
export default function App() {
  return (
    <div className="app-layout">
      <AdminPanel />
      <CustomerWidget />
    </div>
  );
}