JavaScript SDK

import { AnsaClient } from "@ansa-so/sdk";

const ansa = new AnsaClient({
  apiKey: process.env.ANSA_API_KEY!,
});

// Send a message and get a response
const response = await ansa.chat("agent_abc123", "What are your hours?");
console.log(response.message);

import { embedWidget, openWidget, identify } from "@ansa-so/sdk";

// Embed the widget (alternative to script tag)
embedWidget({
  agentId: "agent_abc123",
});

// Identify the logged-in user
identify({
  userId: "user_456",
  userMetadata: {
    name: "Jane Smith",
    email: "jane@example.com",
  },
});

// Open the chat when user clicks a button
document.getElementById("help-btn")?.addEventListener("click", () => {
  openWidget("I need help with my account");
});

interface AnsaConfig {
  /** Your Ansa API key (required) */
  apiKey: string;
  /** API base URL (default: https://api.ansa.so) */
  baseUrl?: string;
  /** Request timeout in milliseconds (default: 30000) */
  timeout?: number;
}

import { AnsaClient, createClient } from "@ansa-so/sdk";

// Using constructor
const ansa = new AnsaClient({
  apiKey: "ansa_sk_...",
  timeout: 60000, // 60 second timeout
});

// Using factory function
const ansa = createClient({
  apiKey: "ansa_sk_...",
});

const response = await ansa.chat("agent_id", "Hello!", {
  conversationId: "conv_123", // Continue existing conversation
  metadata: {
    source: "mobile-app",
    userId: "user_456",
  },
});

console.log(response.message);        // "Hi! How can I help?"
console.log(response.conversationId); // "conv_789"
console.log(response.messageId);      // "msg_abc"
console.log(response.toolCalls);      // [{ id, name, args, result }]

await ansa.chatStream(
  "agent_id",
  "Explain quantum computing",
  {
    onToken: (token) => {
      // Append each token as it arrives
      process.stdout.write(token);
    },
    onToolCall: (toolCall) => {
      console.log(`Tool called: ${toolCall.name}`);
    },
    onMessage: (response) => {
      // Full response when complete
      console.log("\n\nFull message:", response.message);
    },
    onError: (error) => {
      console.error("Stream error:", error);
    },
    onComplete: () => {
      console.log("Stream finished");
    },
  },
  { conversationId: "conv_123" }
);

const agents = await ansa.getAgents();

for (const agent of agents) {
  console.log(`${agent.name} (${agent.id})`);
  console.log(`  Model: ${agent.model}`);
  console.log(`  Temperature: ${agent.temperature}`);
}

const agent = await ansa.getAgent("agent_abc123");

console.log(agent.name);         // "Sales Assistant"
console.log(agent.systemPrompt); // "You are a helpful..."
console.log(agent.model);        // "gpt-4o"

const conversations = await ansa.getConversations("agent_abc123");

for (const conv of conversations) {
  console.log(`${conv.id}: ${conv.messages.length} messages`);
}

const conversation = await ansa.getConversation("conv_xyz789");

for (const message of conversation.messages) {
  console.log(`${message.role}: ${message.content}`);
}

import { openWidget, identify } from "@ansa-so/sdk";

// These calls are safe even before the widget loads
// They're queued and executed once the widget is ready
identify({
  userId: "user_123",
  userMetadata: { name: "Jane" }
});

openWidget("How can I help?");

// Internal SDK pattern (for reference)
function enqueueOrExecute(command: () => void) {
  const api = window.ansa;
  if (api?.isReady?.()) {
    command();
  } else {
    commandQueue.push(command);
    startQueueProcessor(); // Polls every 100ms until ready
  }
}

import { embedWidget } from "@ansa-so/sdk";

embedWidget({
  agentId: "agent_abc123",
  apiUrl: "https://api.ansa.so",      // optional
  widgetUrl: "https://widget.ansa.so", // optional
});

import { openWidget } from "@ansa-so/sdk";

// Just open
openWidget();

// Open with message
openWidget("I'd like to schedule a demo");

import { closeWidget } from "@ansa-so/sdk";

closeWidget();

import { toggleWidget } from "@ansa-so/sdk";

toggleWidget();

import { isWidgetOpen, isWidgetReady } from "@ansa-so/sdk";

if (isWidgetReady() && !isWidgetOpen()) {
  openWidget();
}

import { showBubbles, hideBubbles } from "@ansa-so/sdk";

// Single message
showBubbles("Need help?");

// Multiple messages (appear sequentially)
showBubbles(["👋 Welcome!", "Ask me anything"], 10);

// Hide bubbles
hideBubbles();

import { showForm } from "@ansa-so/sdk";

// Server-side form by name
showForm("contact_form");

// Client-side form with schema
showForm(
  {
    fields: [
      { name: "email", label: "Email", type: "email" },
      { name: "message", label: "Message", type: "textarea" },
    ],
    submitButtonText: "Send",
  },
  {
    onSubmit: (data) => console.log("Form submitted:", data),
    onCancel: () => console.log("Form cancelled"),
    sendToAgent: true, // Also send as chat message
  }
);

import { identify, clearIdentity } from "@ansa-so/sdk";

// On login - include auth token for API calls
identify({
  userId: "user_123",
  userMetadata: {
    name: "Jane Smith",
    email: "jane@example.com",
    plan: "pro",
    authToken: "eyJhbG...",  // Passed to HTTP tools via {{userMetadata.authToken}}
  },
});

// On logout
clearIdentity();

import { getVisitorId } from "@ansa-so/sdk";

const visitorId = getVisitorId();
// "v_1703347200000_abc123def"

import { triggerEvent } from "@ansa-so/sdk";

// Trigger when user views pricing
triggerEvent("viewed_pricing", {
  plan: "enterprise",
  source: "navbar",
});

import { AnsaClient, AnsaError } from "@ansa-so/sdk";

const ansa = new AnsaClient({ apiKey: "..." });

try {
  await ansa.chat("invalid_agent", "Hello");
} catch (error) {
  if (error instanceof AnsaError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);
    console.error(`Code: ${error.code}`);
  }
}

import type {
  AnsaConfig,
  Agent,
  Message,
  ChatOptions,
  ChatResponse,
  ToolCall,
  Conversation,
  StreamCallbacks,
  FormSchema,
  FormField,
  ShowFormOptions,
} from "@ansa-so/sdk";