@syncethic/sdk

The official JavaScript/TypeScript SDK for SyncEthic AI.
Embed an AI chatbot on any website or app in minutes.

Features

• ⚡ Streaming chat — real-time token streaming via ReadableStream
• 💬 Embeddable widget — floating button or inline panel, zero deps
• ⚛️ React support — useChat hook + <ChatWidget> component via @syncethic/sdk/react
• 🌐 CDN ready — <script> tag for WordPress, Shopify, Webflow
• 📝 Custom instructions — add your own context on top of the bot's base prompt
• 🔒 Guardrails respected — instructions extend, never override SyncEthic safety rules
• 🎨 Dark / Light / Auto themes
• 📱 Responsive — mobile-first design
• 🟦 TypeScript first — full type definitions included
• 🛑 Abort support — stop a response mid-stream

Installation

npm install @syncethic/sdk
# or
pnpm add @syncethic/sdk
# or
yarn add @syncethic/sdk

Quick Start

1. Floating Widget (Vanilla JS)

import { SyncEthicWidget } from '@syncethic/sdk';

const widget = new SyncEthicWidget({
  apiKey:   'sk_global_YOUR_KEY',   // from SyncEthic dashboard
  botSlug:  'support_bot',           // marketplace bot slug
  instructions: 'You are the assistant for ACME Corp. Focus on customer support.',
  position: 'bottom-right',
  theme:    'dark',
  primaryColor: '#6366f1',
  botName:  'ACME Support',
  welcomeMessage: 'Hello! How can I help you today?',
});

widget.mountFloating();

2. Inline Embed (Vanilla JS)

import { SyncEthicWidget } from '@syncethic/sdk';

new SyncEthicWidget({
  apiKey:  'sk_global_YOUR_KEY',
  botSlug: 'support_bot',
}).mount('#chat-container');

3. CDN Script Tag (no npm)

<script src="https://cdn.syncethic.ai/sdk/syncethic.min.js"></script>
<script>
  SyncEthic.mount({
    apiKey:   'sk_global_YOUR_KEY',
    botSlug:  'support_bot',
    instructions: 'You are the assistant for my store. Help with orders and products.',
    position: 'bottom-right',
    primaryColor: '#10b981',
  });
</script>

4. React — useChat Hook

import { useChat } from '@syncethic/sdk/react';

function ChatPage() {
  const { messages, sendMessage, isLoading, stop } = useChat({
    apiKey:  'sk_global_YOUR_KEY',
    botSlug: 'support_bot',
    instructions: 'You are our support assistant. Be concise and friendly.',
  });

  return (
    <div>
      {messages.map((m, i) => (
        <p key={i}><b>{m.role}:</b> {m.content}</p>
      ))}
      <button onClick={() => sendMessage('Hello!')}>Send</button>
      {isLoading && <button onClick={stop}>Stop</button>}
    </div>
  );
}

5. React — ChatWidget Component

import { ChatWidget } from '@syncethic/sdk/react';

// In your layout or root component:
<ChatWidget
  apiKey="sk_global_YOUR_KEY"
  botSlug="support_bot"
  instructions="You are the assistant for our SaaS product."
  mode="floating"            // 'floating' | 'embedded'
  position="bottom-right"
  theme="auto"               // 'dark' | 'light' | 'auto'
  primaryColor="#6366f1"
  botName="Support AI"
  welcomeMessage="Hello! Ask me anything."
/>

6. Headless Client (Node.js / Edge)

import { SyncEthicClient } from '@syncethic/sdk';

const client = new SyncEthicClient({
  apiKey:       'sk_global_YOUR_KEY',
  botSlug:      'support_bot',
  instructions: 'You are a triage bot. Categorize user requests in JSON.',
});

// Streaming
await client.chat('My order is late.', [], {
  onChunk: (chunk) => process.stdout.write(chunk),
  onDone:  (full)  => console.log('\nDone:', full),
});

// One-shot (waits for full response)
const { text } = await client.chatSync('Summarize our return policy.');

Configuration Reference

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | apiKey | string | ✅ | — | Global API key (sk_global_...) from SyncEthic dashboard | | botSlug | string | ✅ | — | Bot slug from the marketplace (e.g. support_bot) | | instructions | string | — | — | Custom context appended to the bot's system prompt (max 2000 chars) | | endpoint | string | — | Production URL | Override API endpoint (for proxy setups) | | temperature | number | — | — | Response creativity (0.0 – 1.0) | | maxTokens | number | — | — | Maximum output tokens | | onError | function | — | — | Error callback: (err: SyncEthicError) => void |

Widget-specific Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' \| 'full-page' | 'bottom-right' | Widget position | | theme | 'dark' \| 'light' \| 'auto' | 'auto' | Color theme | | primaryColor | string | '#6366f1' | Accent color (any CSS color) | | logo | string | — | URL to your logo image | | botName | string | 'AI Assistant' | Display name in the widget header | | welcomeMessage | string | 'Hello! How can I help?' | First message shown | | placeholder | string | 'Type a message…' | Input placeholder | | zIndex | number | 99999 | CSS z-index for floating mode |

Custom Instructions

The instructions option lets you add context to your bot without overriding its safety guardrails.

new SyncEthicWidget({
  apiKey:  'sk_global_xxx',
  botSlug: 'support_bot',
  instructions: `
    You are the assistant for PharmaCool pharmacy.
    - Only answer questions about our products and services.
    - Always recommend consulting a licensed pharmacist for medical advice.
    - Our store hours are Mon-Fri 9am-6pm, Sat 10am-4pm.
    - For emergency questions, direct them to call 1-800-PHARMAC.
  `,
});

Note: Instructions are limited to 2000 characters and are appended after the bot's base system prompt. SyncEthic's guardrails (PII masking, content safety) remain fully active.

Security

Protecting your Global API Key

Your global_api_key will be visible in client-side code. To restrict its use:

1. Domain Whitelist — Go to the SyncEthic dashboard → API Keys → Set Allowed Domains.
   Only requests from these domains will be accepted.
   Example: myshop.com, *.myshop.com

2. Server-Side Proxy (recommended for sensitive bots) — Create an API route in your app that adds the key server-side:

   // app/api/chat/route.ts (Next.js)
   export async function POST(req: Request) {
     const body = await req.json();
     return fetch('https://app.syncethic.ai/api/v1/chat', {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
         'x-api-key': process.env.SYNCETHIC_API_KEY!, // server-side only
       },
       body: JSON.stringify(body),
     });
   }

   Then set endpoint: '/api/chat' in your SDK config.

Examples

| Example | Description | |---------|-------------| | examples/vanilla-js | Script tag embed (CDN) | | examples/nextjs | Next.js 16 App Router | | examples/widget-embed | Minimal floating button |

License

MIT © SyncEthic AI