PRD-38.4: SDK Foundation

Version: 1.0 Status: 🟡 Planned Priority: HIGH - Platform Expansion Author: Automatos AI Platform Team Last Updated: 2026-01-27 Dependencies: PRD-38.1, PRD-38.2, PRD-38.3, PRD-32 (Widget Integration System) Timeline: Weeks 8-10

---

Executive Summary

Extract the widget system into a standalone, embeddable SDK that customers can add to their websites and applications. This transforms Automatos from a standalone platform into an embeddable AI service.

The Vision

Customer Website                        Automatos Cloud
─────────────────                       ───────────────
┌─────────────────────┐                 ┌─────────────────────┐
│                     │                 │                     │
│  <script src=       │    ◀──────▶    │  Widget API         │
│   "automatos.js">   │    Secure       │  - Chat             │
│                     │    WebSocket    │  - RAG              │
│  ┌───────────────┐  │    + REST       │  - NL2SQL           │
│  │ Automatos     │  │                 │  - 863+ Tools       │
│  │ Chat Widget   │  │                 │  - Agents           │
│  │               │  │                 │  - Memory           │
│  └───────────────┘  │                 │                     │
│                     │                 └─────────────────────┘
└─────────────────────┘

Key Deliverables

Deliverable	Description
@automatos-ai/core	Core SDK - API client, auth, types
@automatos-ai/react	React components for widgets
@automatos-ai/vanilla	Vanilla JS for script tag embedding
cdn.automatos.app/widget.js	CDN-hosted script loader
Documentation Site	Developer documentation and playground

---

1) Goals & Success Metrics

Goals

ID	Goal	Description
G1	Easy Integration	< 5 lines of code to embed
G2	Framework Agnostic	Works with React, Vue, vanilla JS, WordPress
G3	Small Bundle	< 50KB gzipped per widget
G4	Secure	API key auth, tenant isolation
G5	Performant	< 500ms load time from CDN

Success Metrics

Metric	Target	Measurement
Script tag integration time	< 15 minutes	User testing
Bundle size (chat widget)	< 50KB gzipped	Build output
CDN load time	< 500ms (p95)	Cloudflare analytics
First message latency	< 2s	Performance monitoring
Documentation coverage	100% of widgets	Doc review

---

2) Repository Structure

New Repository: automatos-widgets

automatos-widgets/
├── .github/
│   ├── workflows/
│   │   ├── ci.yml              # Test and lint
│   │   ├── release.yml         # NPM publish
│   │   └── docs.yml            # Deploy docs
│   └── CODEOWNERS
│
├── packages/
│   ├── core/                   # @automatos-ai/core
│   │   ├── src/
│   │   │   ├── index.ts
│   │   │   ├── client.ts       # API client
│   │   │   ├── auth.ts         # Authentication
│   │   │   ├── types.ts        # Shared types
│   │   │   ├── events.ts       # Event emitter
│   │   │   └── utils.ts
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── README.md
│   │
│   ├── react/                  # @automatos-ai/react
│   │   ├── src/
│   │   │   ├── index.ts
│   │   │   ├── AutomatosProvider.tsx
│   │   │   ├── ChatWidget.tsx
│   │   │   ├── DataWidget.tsx
│   │   │   ├── DocumentWidget.tsx
│   │   │   └── hooks/
│   │   │       ├── useChat.ts
│   │   │       └── useWidget.ts
│   │   ├── package.json
│   │   └── README.md
│   │
│   ├── vanilla/                # @automatos-ai/vanilla
│   │   ├── src/
│   │   │   ├── index.ts
│   │   │   ├── loader.ts       # Script tag loader
│   │   │   ├── embed.ts        # Embedding logic
│   │   │   └── widgets/
│   │   │       ├── chat.ts
│   │   │       └── data.ts
│   │   ├── package.json
│   │   └── README.md
│   │
│   └── web-components/         # @automatos-ai/wc (future)
│       └── ...
│
├── apps/
│   ├── docs/                   # Documentation site (Nextra/Docusaurus)
│   │   ├── pages/
│   │   │   ├── index.mdx
│   │   │   ├── getting-started.mdx
│   │   │   ├── react.mdx
│   │   │   ├── vanilla.mdx
│   │   │   ├── widgets/
│   │   │   │   ├── chat.mdx
│   │   │   │   ├── data.mdx
│   │   │   │   └── ...
│   │   │   └── api-reference.mdx
│   │   └── package.json
│   │
│   └── playground/             # Interactive widget playground
│       ├── src/
│       └── package.json
│
├── examples/
│   ├── nextjs/                 # Next.js integration
│   │   ├── app/
│   │   ├── package.json
│   │   └── README.md
│   │
│   ├── create-react-app/       # CRA integration
│   │   └── ...
│   │
│   ├── html/                   # Plain HTML integration
│   │   ├── index.html
│   │   └── README.md
│   │
│   ├── wordpress/              # WordPress plugin
│   │   ├── automatos-widget.php
│   │   └── README.md
│   │
│   └── shopify/                # Shopify app
│       └── ...
│
├── package.json                # Root package.json
├── turbo.json                  # Turborepo config
├── tsconfig.base.json          # Shared TS config
└── README.md

---

3) Package Specifications

3.1 @automatos-ai/core

Purpose: Core SDK with API client, authentication, and shared utilities.

Installation:

npm install @automatos-ai/core

Usage:

import { AutomatosClient } from '@automatos-ai/core'

const client = new AutomatosClient({
  apiKey: 'your-api-key',
  workspaceId: 'your-workspace-id',
  // Optional
  baseUrl: 'https://api.automatos.app',
  timeout: 30000,
})

// Chat
const response = await client.chat.send({
  message: 'Hello!',
  conversationId: 'optional-id',
})

// Stream chat
for await (const chunk of client.chat.stream({ message: 'Hello!' })) {
  console.log(chunk)
}

// Search documents
const docs = await client.documents.search({
  query: 'How does X work?',
  limit: 5,
})

// Query database
const results = await client.data.query({
  question: 'Show me sales this month',
})

API:

// packages/core/src/client.ts

export interface AutomatosClientOptions {
  apiKey: string
  workspaceId: string
  baseUrl?: string
  timeout?: number
  onError?: (error: AutomatosError) => void
  onTokenRefresh?: () => Promise<string>
}

export class AutomatosClient {
  constructor(options: AutomatosClientOptions)

  // Namespaced APIs
  chat: ChatAPI
  documents: DocumentsAPI
  data: DataAPI
  agents: AgentsAPI
  workflows: WorkflowsAPI
  memory: MemoryAPI

  // Events
  on(event: string, handler: Function): void
  off(event: string, handler: Function): void

  // Connection
  connect(): Promise<void>
  disconnect(): void
  isConnected(): boolean
}

// Chat API
export interface ChatAPI {
  send(request: ChatRequest): Promise<ChatResponse>
  stream(request: ChatRequest): AsyncIterable<ChatChunk>
  getHistory(conversationId: string): Promise<Message[]>
}

// Documents API
export interface DocumentsAPI {
  search(request: SearchRequest): Promise<Document[]>
  get(documentId: string): Promise<Document>
}

// Data API
export interface DataAPI {
  query(request: DataQueryRequest): Promise<DataQueryResponse>
  execute(sql: string): Promise<DataQueryResponse>
}

3.2 @automatos-ai/react

Purpose: React components and hooks for embedding widgets.

Installation:

npm install @automatos-ai/react @automatos-ai/core

Usage:

import { AutomatosProvider, ChatWidget, DataWidget } from '@automatos-ai/react'

function App() {
  return (
    <AutomatosProvider
      apiKey="your-api-key"
      workspaceId="your-workspace-id"
    >
      <div className="my-app">
        {/* Floating chat widget */}
        <ChatWidget
          position="bottom-right"
          placeholder="Ask anything..."
          theme="dark"
        />

        {/* Inline data widget */}
        <DataWidget
          query="Show me recent orders"
          title="Recent Orders"
          showCharts
        />
      </div>
    </AutomatosProvider>
  )
}

Components:

// packages/react/src/index.ts

// Provider
export { AutomatosProvider } from './AutomatosProvider'
export type { AutomatosProviderProps } from './AutomatosProvider'

// Widgets
export { ChatWidget } from './ChatWidget'
export { DataWidget } from './DataWidget'
export { DocumentWidget } from './DocumentWidget'
export { CodeWidget } from './CodeWidget'
export { ImageWidget } from './ImageWidget'

// Hooks
export { useAutomatos } from './hooks/useAutomatos'
export { useChat } from './hooks/useChat'
export { useWidget } from './hooks/useWidget'

// Types
export type {
  ChatWidgetProps,
  DataWidgetProps,
  DocumentWidgetProps,
  Theme,
  Position,
} from './types'

ChatWidget Props:

interface ChatWidgetProps {
  // Appearance
  position?: 'bottom-right' | 'bottom-left' | 'inline'
  theme?: 'light' | 'dark' | 'system' | ThemeConfig
  size?: 'small' | 'medium' | 'large'
  className?: string
  style?: React.CSSProperties

  // Behavior
  placeholder?: string
  welcomeMessage?: string
  suggestedQuestions?: string[]
  agentId?: number
  modelId?: string

  // Features
  showHistory?: boolean
  showSources?: boolean
  showToolCalls?: boolean
  enableAttachments?: boolean
  enableVoice?: boolean

  // Callbacks
  onMessage?: (message: Message) => void
  onToolCall?: (toolCall: ToolCall) => void
  onError?: (error: Error) => void
  onOpen?: () => void
  onClose?: () => void
}

3.3 @automatos-ai/vanilla

Purpose: Vanilla JavaScript for script tag embedding (no framework required).

CDN Usage:

<!-- Add to your HTML -->
<script src="https://cdn.automatos.app/widget.js"></script>
<script>
  Automatos.init({
    apiKey: 'your-api-key',
    workspaceId: 'your-workspace-id',
  })

  // Chat widget
  Automatos.widgets.chat({
    container: '#chat-container',
    // or use floating mode
    position: 'bottom-right',
  })

  // Data widget
  Automatos.widgets.data({
    container: '#data-widget',
    query: 'Show me sales this week',
  })
</script>

<div id="chat-container"></div>
<div id="data-widget"></div>

Script Tag Attributes:

<!-- Simple one-liner -->
<script
  src="https://cdn.automatos.app/widget.js"
  data-automatos-api-key="your-api-key"
  data-automatos-workspace-id="your-workspace-id"
  data-automatos-widget="chat"
  data-automatos-position="bottom-right"
></script>

⚠️ Security Warning: API Keys in Client-Side HTML

CRITICAL: Embedding data-automatos-api-key directly in HTML exposes keys to:

• End users via browser DevTools (View Source, Network tab)

• Web crawlers and scrapers

• Browser extensions with page access

• Any JavaScript on the page

This approach should ONLY be used with "public" client-side keys that have:

1. Restricted Permissions: Only allow non-sensitive operations

   // Public key allowed operations (whitelist)
   const PUBLIC_KEY_PERMISSIONS = [
     'chat:send',           // Send chat messages
     'chat:read',           // Read own conversation
     'documents:search',    // Search public knowledge base
     // NEVER: 'admin:*', 'billing:*', 'users:*', etc.
   ]

2. Strict Domain Binding: Key only works from specific origins

   // API key creation - domain binding is REQUIRED for public keys
   const publicKey = await createApiKey({
     type: 'public',
     allowedDomains: ['example.com', '*.example.com'],  // Required
     // Rejects requests from any other origin
   })

3. Aggressive Rate Limiting: Prevent abuse

   // Public key rate limits (much stricter than server keys)
   const PUBLIC_KEY_RATE_LIMITS = {
     requestsPerMinute: 30,      // vs 1000 for server keys
     tokensPerDay: 10000,        // vs unlimited for server keys
     concurrentRequests: 3,      // vs 50 for server keys
   }

Recommended: Server-Mediated Token Exchange

For production deployments, use a server-mediated flow instead of exposing API keys:

// ❌ BAD: API key in HTML (visible to everyone)
<script data-automatos-api-key="ak_live_xxx"></script>

// ✅ GOOD: Server-issued short-lived session token
// Step 1: Your backend exchanges API key for session token
// (Server-side, API key never sent to browser)
app.get('/api/automatos-token', async (req, res) => {
  // Verify user is authenticated on YOUR system
  if (!req.user) return res.status(401).json({ error: 'Unauthorized' })

  // Exchange your API key for a short-lived session token
  const sessionToken = await automatosClient.auth.createSessionToken({
    apiKey: process.env.AUTOMATOS_API_KEY,  // Server-side secret
    userId: req.user.id,                     // Your user's ID
    expiresIn: '1h',                         // Short-lived
    permissions: ['chat:send', 'chat:read'], // Scoped permissions
  })

  res.json({ token: sessionToken })
})

// Step 2: Frontend fetches token and initializes widget
async function initWidget() {
  const { token } = await fetch('/api/automatos-token').then(r => r.json())

  Automatos.init({
    sessionToken: token,  // Short-lived, scoped token
    workspaceId: 'ws_xxx',
    // NO apiKey - token is exchanged server-side
  })
}

Benefits of server-mediated approach:

• API key never exposed to client

• Tokens are short-lived (1 hour default)

• Tokens are scoped to specific user and permissions

• Revocation is immediate (vs API key rotation)

• Audit trail of token issuance

Documentation must clearly state:

• Public keys = limited permissions + domain binding + rate limiting

• Server tokens = recommended for production

• Examples should show both approaches with security tradeoffs

Implementation:

// packages/vanilla/src/loader.ts

interface AutomatosConfig {
  apiKey: string
  workspaceId: string
  baseUrl?: string
}

interface WidgetOptions {
  container?: string | HTMLElement
  position?: 'bottom-right' | 'bottom-left'
  theme?: 'light' | 'dark'
  // ... widget-specific options
}

declare global {
  interface Window {
    Automatos: {
      init: (config: AutomatosConfig) => void
      widgets: {
        chat: (options?: WidgetOptions) => ChatWidgetInstance
        data: (options?: WidgetOptions) => DataWidgetInstance
        document: (options?: WidgetOptions) => DocumentWidgetInstance
      }
      destroy: () => void
    }
  }
}

// Auto-initialize from script attributes
(function() {
  const script = document.currentScript as HTMLScriptElement
  if (!script) return

  const apiKey = script.dataset.automatosApiKey
  const workspaceId = script.dataset.automatosWorkspaceId
  const widget = script.dataset.automatosWidget

  if (apiKey && workspaceId) {
    window.Automatos.init({ apiKey, workspaceId })

    if (widget) {
      const position = script.dataset.automatosPosition as any
      window.Automatos.widgets[widget]?.({ position })
    }
  }
})()

---

4) API Endpoints

Widget API (Backend)

# Authentication
POST /api/widgets/auth           # Exchange API key for session token

# Chat
POST /api/widgets/chat           # Send message (streaming)
GET  /api/widgets/chat/:id       # Get conversation
DELETE /api/widgets/chat/:id     # Delete conversation

# Documents
POST /api/widgets/documents/search   # Search knowledge base
GET  /api/widgets/documents/:id      # Get document

# Data
POST /api/widgets/data/query     # Natural language query
POST /api/widgets/data/execute   # Execute SQL

# Agents
GET  /api/widgets/agents         # List available agents
POST /api/widgets/agents/:id/run # Run agent

# Workflows
POST /api/widgets/workflows/:id/run    # Trigger workflow
GET  /api/widgets/workflows/:id/status # Get status

# Memory
GET  /api/widgets/memory         # Get relevant memories
POST /api/widgets/memory         # Store memory

Headers:

Authorization: Bearer <api-key>
X-Workspace-ID: <workspace-id>
X-Widget-Type: chat | data | document
X-Request-ID: <unique-id>

Streaming Response:

Content-Type: text/event-stream

event: message
data: {"type":"text","content":"Hello"}

event: tool-start
data: {"type":"tool-start","toolName":"search_knowledge","toolCallId":"abc123"}

event: tool-end
data: {"type":"tool-end","toolCallId":"abc123","success":true}

event: tool-data
data: {"type":"tool-data","documents":[...]}

event: done
data: {"type":"done","usage":{"tokens":150}}

---

5) Security

API Key Management

// API Key structure
interface ApiKey {
  id: string
  workspaceId: string
  name: string
  keyPrefix: string      // First 8 chars (for display)
  keyHash: string        // Hashed full key

  // Permissions
  permissions: Permission[]

  // Rate limiting
  rateLimit: {
    requests: number     // Per minute
    tokens: number       // Per day
  }

  // Restrictions
  allowedDomains?: string[]   // CORS origins
  allowedIPs?: string[]       // IP whitelist

  // Metadata
  createdAt: Date
  expiresAt?: Date
  lastUsedAt?: Date
}

type Permission =
  | 'chat'
  | 'documents:read'
  | 'data:query'
  | 'agents:run'
  | 'workflows:run'
  | 'memory:read'
  | 'memory:write'

Security Measures

Measure	Implementation
API Key Auth	SHA-256 hashed, rotatable
Domain Restriction	CORS origin validation
Rate Limiting	Per-key limits (Redis)
Tenant Isolation	All queries scoped to workspace
Input Validation	Zod schemas on all inputs
Output Sanitization	XSS prevention
CSP Headers	Strict Content-Security-Policy

CORS Configuration

// Backend CORS middleware
const corsOptions = {
  origin: (origin, callback) => {
    // Check if origin is in API key's allowedDomains
    const apiKey = getApiKeyFromRequest()
    if (!apiKey.allowedDomains || apiKey.allowedDomains.includes(origin)) {
      callback(null, true)
    } else {
      callback(new Error('Not allowed by CORS'))
    }
  },
  credentials: true,
  maxAge: 86400, // 24 hours
}

---

6) CDN & Distribution

Cloudflare Setup

cdn.automatos.app/
├── widget.js           # Main loader (always latest)
├── widget.min.js       # Minified
├── v1/
│   ├── widget.js
│   └── widget.min.js
├── v2/
│   └── ...
└── chunks/             # Code-split chunks
    ├── chat.[hash].js
    ├── data.[hash].js
    └── ...

Build Configuration:

// vite.config.ts for vanilla package

export default defineConfig({
  build: {
    lib: {
      entry: 'src/index.ts',
      name: 'Automatos',
      formats: ['iife', 'es', 'umd'],
      fileName: (format) => `widget.${format}.js`,
    },
    rollupOptions: {
      output: {
        manualChunks: {
          chat: ['./src/widgets/chat.ts'],
          data: ['./src/widgets/data.ts'],
          document: ['./src/widgets/document.ts'],
        },
      },
    },
    minify: 'terser',
    sourcemap: true,
  },
})

Versioning Strategy

Semantic Versioning: MAJOR.MINOR.PATCH

Latest: cdn.automatos.app/widget.js (always latest stable)
Pinned: cdn.automatos.app/v1/widget.js (major version)
Exact:  cdn.automatos.app/v1.2.3/widget.js (exact version)

Deprecation Policy:
- Major versions supported for 12 months after next major release
- Security patches backported to supported versions

---

7) Implementation Plan

Week 8: Core Package + API

Day	Task
1	Set up monorepo with Turborepo
2	Implement @automatos-ai/core API client
3	Add authentication and streaming
4	Backend: Widget API endpoints
5	Testing and documentation

Week 9: React Package

Day	Task
1	AutomatosProvider and hooks
2	ChatWidget component
3	DataWidget, DocumentWidget
4	Theming system
5	Testing with Next.js example

Week 10: Vanilla Package + CDN

Day	Task
1	Vanilla JS loader
2	Script tag auto-initialization
3	Build pipeline for CDN
4	Deploy to Cloudflare
5	Documentation site launch

---

8) Files to Create

In automatos-widgets repo:

packages/core/src/
├── index.ts
├── client.ts
├── auth.ts
├── types.ts
├── events.ts
├── chat.ts
├── documents.ts
├── data.ts
└── utils.ts

packages/react/src/
├── index.ts
├── AutomatosProvider.tsx
├── ChatWidget.tsx
├── DataWidget.tsx
├── DocumentWidget.tsx
├── hooks/
│   ├── useAutomatos.ts
│   ├── useChat.ts
│   └── useWidget.ts
├── components/
│   ├── MessageList.tsx
│   ├── InputBar.tsx
│   └── WidgetContainer.tsx
└── styles/
    └── widget.css

packages/vanilla/src/
├── index.ts
├── loader.ts
├── embed.ts
├── render.ts
└── widgets/
    ├── chat.ts
    ├── data.ts
    └── document.ts

In main automatos-ai repo:

backend/
├── api/widgets/
│   ├── __init__.py
│   ├── router.py
│   ├── auth.py
│   ├── chat.py
│   ├── documents.py
│   ├── data.py
│   └── rate_limit.py
└── models/
    └── api_key.py

---

9) Example Integrations

Next.js Integration

// app/layout.tsx
import { AutomatosProvider } from '@automatos-ai/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <AutomatosProvider
          apiKey={process.env.NEXT_PUBLIC_AUTOMATOS_API_KEY!}
          workspaceId={process.env.NEXT_PUBLIC_AUTOMATOS_WORKSPACE_ID!}
        >
          {children}
        </AutomatosProvider>
      </body>
    </html>
  )
}

// app/page.tsx
import { ChatWidget } from '@automatos-ai/react'

export default function Home() {
  return (
    <main>
      <h1>My App</h1>
      <ChatWidget position="bottom-right" />
    </main>
  )
}

WordPress Integration

<?php
/**
 * Plugin Name: Automatos AI Widget
 * Description: Add Automatos AI chat widget to your WordPress site
 * Version: 1.0.0
 */

function automatos_enqueue_widget() {
    $api_key = get_option('automatos_api_key');
    $workspace_id = get_option('automatos_workspace_id');

    if (!$api_key || !$workspace_id) return;

    wp_enqueue_script(
        'automatos-widget',
        'https://cdn.automatos.app/widget.js',
        [],
        null,
        true
    );

    wp_add_inline_script('automatos-widget', "
        Automatos.init({
            apiKey: '{$api_key}',
            workspaceId: '{$workspace_id}'
        });
        Automatos.widgets.chat({ position: 'bottom-right' });
    ");
}
add_action('wp_enqueue_scripts', 'automatos_enqueue_widget');

// Settings page
function automatos_settings_page() {
    add_options_page(
        'Automatos AI Settings',
        'Automatos AI',
        'manage_options',
        'automatos-ai',
        'automatos_settings_html'
    );
}
add_action('admin_menu', 'automatos_settings_page');

Plain HTML Integration

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to My Website</h1>

  <!-- Automatos Chat Widget -->
  <script
    src="https://cdn.automatos.app/widget.js"
    data-automatos-api-key="your-api-key"
    data-automatos-workspace-id="your-workspace-id"
    data-automatos-widget="chat"
    data-automatos-position="bottom-right"
    data-automatos-theme="dark"
  ></script>
</body>
</html>

---

10) Testing Checklist

Core Package

• API client connects successfully

• Authentication works

• Streaming responses handled

• Error handling correct

• Types exported properly

React Package

• Provider initializes correctly

• ChatWidget renders

• Messages send and receive

• Theming works

• All widgets functional

• SSR compatible

Vanilla Package

• Script loads from CDN

• Auto-initialization works

• Manual initialization works

• Widget renders in container

• Floating position works

• No global conflicts

Security

• Invalid API key rejected

• Domain restriction enforced

• Rate limiting works

• XSS prevented

• Tenant isolation verified

---

11) Success Criteria

Phase 4 is complete when:

• All three packages published to npm

• CDN serving widget.js

• Next.js example working

• WordPress plugin working

• HTML example working

• Documentation site live

• Bundle size < 50KB (chat widget)

• Load time < 500ms from CDN

• 100% type coverage

• Security audit passed

---

12) References

• Intercom Messenger SDK

• Zendesk Widget API

• Crisp Chat SDK

• Turborepo

• Vite Library Mode

• PRD-32: Widget Integration System

---

Document Version: 1.0 Created: 2026-01-27 Estimated Implementation: 3 weeks