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,
        // baseUrl: "http://localhost:3100", // dev only
      }}
    />
  );
}

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 { SyncAgentClient } from "@syncagent/js";

const agent = new SyncAgentClient({
  apiKey: "sa_your_key",
  connectionString: process.env.DATABASE_URL,
  // baseUrl: "http://localhost:3100", // dev only
});

// 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);

// 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;
        },
      }}
    />
  );
}

<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>

// 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}`));

<SyncAgentChat
  config={{
    apiKey: "sa_your_key",
    connectionString: process.env.DATABASE_URL,
    tools: {
      sendEmail: {
        description: "Send an email to a user",
        inputSchema: {
          to:      { type: "string", description: "Recipient email address" },
          subject: { type: "string", description: "Email subject line" },
          body:    { type: "string", description: "Email body (plain text)" },
        },
        execute: async ({ to, subject, body }) => {
          // Your email logic — runs in YOUR app
          await resend.emails.send({ from: "noreply@yourapp.com", to, subject, text: body });
          return { sent: true, to };
        },
      },
    },
  }}
/>

// Now users can say: "Email all users whose subscription expired"
// The agent will query expired users, then call sendEmail for each one

const agent = new SyncAgentClient({
  apiKey: "sa_your_key",
  connectionString: process.env.DATABASE_URL,
  tools: {
    sendSlackAlert: {
      description: "Post an alert to a Slack channel",
      inputSchema: {
        channel: { type: "string", description: "Channel name e.g. #alerts" },
        message: { type: "string", description: "Alert message" },
        severity: { type: "string", description: "low | medium | high", enum: ["low","medium","high"] },
      },
      execute: async ({ channel, message, severity }) => {
        await slack.chat.postMessage({ channel, text: `[${severity.toUpperCase()}] ${message}` });
        return { posted: true };
      },
    },
    createStripeInvoice: {
      description: "Create a Stripe invoice for a customer",
      inputSchema: {
        customerId: { type: "string", description: "Stripe customer ID" },
        amount:     { type: "number", description: "Amount in cents" },
        description:{ type: "string", description: "Invoice description" },
      },
      execute: async ({ customerId, amount, description }) => {
        const invoice = await stripe.invoices.create({
          customer: customerId,
          description,
          collection_method: "send_invoice",
          days_until_due: 30,
        });
        await stripe.invoiceItems.create({ customer: customerId, amount, invoice: invoice.id });
        await stripe.invoices.finalizeInvoice(invoice.id);
        return { invoiceId: invoice.id, status: invoice.status };
      },
    },
    generatePdfReport: {
      description: "Generate a PDF report and return the download URL",
      inputSchema: {
        title:   { type: "string", description: "Report title" },
        content: { type: "string", description: "Report content as markdown" },
      },
      execute: async ({ title, content }) => {
        const url = await pdfService.generate({ title, markdown: content });
        return { url, generatedAt: new Date().toISOString() };
      },
    },
  },
});

// "Find all overdue invoices, create Stripe invoices for them, and post a summary to #billing"
// The agent will: query DB → create invoices → post Slack message → report back

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

<SyncAgentChat
  config={{
    apiKey: "sa_your_key",
    toolsOnly: true,
    tools: {
      searchProducts: {
        description: "Search products by name or category",
        inputSchema: {
          query: { type: "string", description: "Search query" },
        },
        execute: async ({ query }) => {
          const res = await fetch(`/api/products?q=${query}`);
          return res.json();
        },
      },
      createOrder: {
        description: "Place an order for a product",
        inputSchema: {
          productId: { type: "string", description: "Product ID" },
          quantity:  { type: "number", description: "Quantity" },
        },
        execute: async ({ productId, quantity }) => {
          const res = await fetch("/api/orders", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ productId, quantity }),
          });
          return res.json();
        },
      },
    },
  }}
/>

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

const agent = new SyncAgentClient({
  apiKey: "sa_your_key",
  toolsOnly: true,
  tools: {
    getWeather: {
      description: "Get current weather for a city",
      inputSchema: {
        city: { type: "string", description: "City name" },
      },
      execute: async ({ city }) => {
        const res = await fetch(`https://api.weather.com/v1/${city}`);
        return res.json();
      },
    },
  },
});

const result = await agent.chat([
  { role: "user", content: "What's the weather in Accra?" }
]);
console.log(result.text);

curl -X POST https://syncagent.dev/api/v1/chat \
  -H "Authorization: Bearer sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "toolsOnly": true,
    "clientTools": {
      "searchProducts": {
        "description": "Search products by name",
        "inputSchema": {
          "query": { "type": "string", "description": "Search query" }
        }
      }
    },
    "messages": [{
      "id": "1",
      "role": "user",
      "parts": [{ "type": "text", "text": "Find running shoes" }]
    }]
  }'

// In your app, after the user logs in:
import { SyncAgentChat } from "@syncagent/react";

export default function Dashboard({ currentUser }) {
  return (
    <SyncAgentChat
      config={{
        apiKey: process.env.NEXT_PUBLIC_SYNCAGENT_KEY,
        connectionString: process.env.DATABASE_URL,
        // Scope ALL queries to this organization
        filter: { organizationId: currentUser.orgId },
      }}
    />
  );
}

// Every operation is now scoped:
// "Show all orders"  → db.orders.find({ organizationId: "org_123" })
// "Count users"      → db.users.countDocuments({ organizationId: "org_123" })
// "Add a product"    → db.products.insertOne({ ...doc, organizationId: "org_123" })

<SyncAgentChat
  config={{
    apiKey: process.env.NEXT_PUBLIC_SYNCAGENT_KEY,
    connectionString: process.env.DATABASE_URL,
    filter: { organizationId: currentUser.orgId },
    // Admins get full access, regular users read-only
    operations: currentUser.role === "admin"
      ? ["read", "create", "update", "delete"]
      : ["read"],
  }}
/>

// By organization ID (most common)
filter: { organizationId: org.id }

// By tenant slug
filter: { tenant: "acme-corp" }

// Personal data — scope to current user
filter: { userId: currentUser.id }

// Multiple conditions
filter: { orgId: org.id, deleted: false }

// SQL databases (same syntax)
filter: { tenant_id: tenant.id }

Allowed Collections: users, orders, products
(blank = all collections)

Blocked Collections: admin_logs, secrets, audit_trail
(always denied, overrides allowed list)

URL: /dashboard/orders/ord_123?tab=details&status=active

Auto-detected context:
  currentPage: "orders"              ← last meaningful path segment
  currentPath: "/dashboard/orders/ord_123"
  currentRecordId: "ord_123"         ← detected as ID (ObjectId/UUID/numeric)
  param_tab: "details"               ← useful query params
  param_status: "active"

URL: /app/settings#billing

  currentPage: "settings"
  currentPath: "/app/settings"
  currentSection: "billing"          ← from hash fragment

<SyncAgentChat
  config={{ apiKey: "...", connectionString: "..." }}
  context={{
    userId: currentUser.id,
    userRole: currentUser.role,
    orgName: currentOrg.name,
    currentDate: new Date().toISOString(),
  }}
/>

// Final context sent to the AI:
// {
//   currentPage: "orders",        ← auto-detected
//   currentPath: "/dashboard/orders",
//   userId: "u_123",              ← developer-provided
//   userRole: "admin",
//   orgName: "Acme Corp",
//   currentDate: "2025-07-14T..."
// }

// Disable auto page detection — only use manually passed context
<SyncAgentChat
  config={{
    apiKey: "...",
    connectionString: "...",
    autoDetectPage: false,
  }}
  context={{ page: "custom-page", recordId: "123" }}
/>

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

const agent = new SyncAgentClient({
  apiKey: "sa_your_key",
  connectionString: process.env.DATABASE_URL,
  // autoDetectPage: true (default)
});

// Auto-detection happens automatically on every chat() call
await agent.chat(messages);

// Or pass extra context:
await agent.chat(messages, {
  context: { userId: "u_123", userRole: "admin" }
});

<SyncAgentChat
  config={{
    apiKey: "sa_your_key",
    connectionString: process.env.DATABASE_URL,
    systemInstruction: "You are a friendly sales assistant for Acme Corp. Always suggest upsells when showing order data. Never mention competitor names.",
  }}
/>

<SyncAgentChat
  config={{
    apiKey: "sa_your_key",
    connectionString: process.env.DATABASE_URL,
    language: "French", // or "Spanish", "Japanese", "Arabic", "Twi", etc.
  }}
/>

// User: "Show me all orders"
// Agent: "Voici toutes les commandes..."  

<SyncAgentChat
  config={{
    apiKey: "sa_your_key",
    connectionString: process.env.DATABASE_URL,
    confirmWrites: true,
  }}
/>

// User: "Add a new customer named John"
// Agent: "I'd like to create a record in customers:
  - name: John
Should I proceed?"
// User: "yes"
// Agent: "✅ Created customer John (id: 507f...)"  

// Mobile app — small results
<SyncAgentChat config={{ ..., maxResults: 10 }} />

// Admin dashboard — large results
<SyncAgentChat config={{ ..., maxResults: 100 }} />

<SyncAgentChat
  config={{
    apiKey: "sa_your_key",
    connectionString: process.env.DATABASE_URL,
    sensitiveFields: ["ssn", "creditCard", "salary", "bankAccount"],
  }}
/>

// Agent shows: ssn: "••••••••", salary: "••••••••"  

<SyncAgentChat
  config={{
    apiKey: "sa_your_key",
    connectionString: process.env.DATABASE_URL,
    tools: { /* your custom tools */ },

    // Block specific operations dynamically
    onBeforeToolCall: (toolName, args) => {
      console.log(`[Audit] ${toolName}`, args);
      if (toolName === "deleteUser" && !currentUser.isAdmin) return false;
      return true; // allow
    },

    // Log every result
    onAfterToolCall: (toolName, args, result) => {
      analytics.track("tool_call", { tool: toolName, success: result.success });
    },
  }}
/>

curl -X POST https://syncagent.dev/api/v1/chat \
  -H "Authorization: Bearer sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionString": "mongodb+srv://user:pass@cluster/db",
    "messages": [{
      "id": "1",
      "role": "user",
      "parts": [{ "type": "text", "text": "Show all active users" }]
    }]
  }'

import requests

res = requests.post(
    "https://syncagent.dev/api/v1/chat",
    headers={"Authorization": "Bearer sa_your_key"},
    json={
        "connectionString": "mongodb+srv://user:pass@cluster/db",
        "messages": [{
            "id": "1", "role": "user",
            "parts": [{"type": "text", "text": "Show all active users"}]
        }]
    },
    stream=True
)
for chunk in res.iter_content(decode_unicode=True):
    print(chunk, end="")

body, _ := json.Marshal(map[string]any{
    "connectionString": "mongodb+srv://user:pass@cluster/db",
    "messages": []map[string]any{{
        "id": "1", "role": "user",
        "parts": []map[string]string{{"type": "text", "text": "Show all active users"}},
    }},
})
req, _ := http.NewRequest("POST", "https://syncagent.dev/api/v1/chat", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer sa_your_key")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
io.Copy(os.Stdout, res.Body)

curl -X POST https://syncagent.dev/api/v1/schema \
  -H "Authorization: Bearer sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "connectionString": "mongodb+srv://user:pass@cluster/db" }'

# Response:
# {
#   "success": true,
#   "dbType": "mongodb",
#   "collections": [
#     {
#       "name": "users",
#       "documentCount": 1247,
#       "fields": [
#         { "name": "_id", "type": "ObjectId" },
#         { "name": "email", "type": "string", "sample": "user@example.com" },
#         { "name": "createdAt", "type": "Date" }
#       ]
#     }
#   ]
# }

curl -X POST https://syncagentdev.vercel.app/api/v1/conversations \
  -H "Authorization: Bearer sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "title": "Order analysis",
    "messages": [
      { "role": "user", "content": "Show all orders over $500" },
      { "role": "assistant", "content": "Here are 12 orders..." }
    ],
    "metadata": { "page": "orders" }
  }'

# Response:
# { "success": true, "conversation": { "id": "conv_abc", "title": "Order analysis", "messageCount": 2 } }

curl https://syncagentdev.vercel.app/api/v1/conversations?userId=user_123&limit=20 \
  -H "Authorization: Bearer sa_your_key"

# Response:
# { "success": true, "conversations": [...], "total": 42, "limit": 20, "offset": 0 }

curl https://syncagentdev.vercel.app/api/v1/conversations/conv_abc \
  -H "Authorization: Bearer sa_your_key"

# Response:
# { "success": true, "conversation": { "id": "conv_abc", "messages": [...], "metadata": {...} } }

curl -X DELETE https://syncagentdev.vercel.app/api/v1/conversations \
  -H "Authorization: Bearer sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "id": "conv_abc" }'

curl -X POST https://syncagentdev.vercel.app/api/v1/conversations \
  -H "Authorization: Bearer sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "conv_abc",
    "messages": [
      { "role": "user", "content": "Show all orders over $500" },
      { "role": "assistant", "content": "Here are 12 orders..." },
      { "role": "user", "content": "Now filter by this month" },
      { "role": "assistant", "content": "Found 3 orders this month..." }
    ]
  }'

// Key with read-only access (for public-facing widget)
// Generated in dashboard with operations: ["read"]

// Key with full access (for admin panel)
// Generated in dashboard with operations: ["read", "create", "update", "delete"]

// The SDK can further restrict at runtime:
const agent = new SyncAgentClient({
  apiKey: "sa_readonly_key",  // this key only allows "read"
  connectionString: process.env.DATABASE_URL,
  operations: ["read", "create"],  // "create" is ignored — key doesn't allow it
});
// Effective operations: ["read"]

// ✅ CORRECT — server component passes connection string
// app/dashboard/page.tsx (server component)
import { SyncAgentChat } from "@syncagent/react";

export default function DashboardPage() {
  return (
    <SyncAgentChat
      config={{
        apiKey: process.env.NEXT_PUBLIC_SYNCAGENT_KEY, // public key is fine
        connectionString: process.env.DATABASE_URL,    // server-only env var
      }}
    />
  );
}

// ❌ WRONG — never do this in a client component
// "use client"
// const conn = process.env.NEXT_PUBLIC_DATABASE_URL; // exposed to browser!

// Verify webhook signature in your endpoint
import crypto from "crypto";

app.post("/webhooks/syncagent", (req, res) => {
  const signature = req.headers["x-syncagent-signature"];
  const body = JSON.stringify(req.body);
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET)
    .update(body)
    .digest("hex");

  if (signature !== expected) {
    return res.status(401).send("Invalid signature");
  }

  const { event, data } = req.body;
  // event: "usage.50" | "usage.80" | "usage.100"
  console.log(`Usage alert: ${data.percentage}% (${data.used}/${data.limit})`);
  res.json({ received: true });
});