Aura AI SDK

The official SDK for integrating the Aura AI Chat Widget into your web applications.

This SDK handles the injection of the widget script, provides type-safe configuration, and allows you to bridge your frontend code to the AI agent using Tools and Context.

Features

• 🚀 Auto-Initialization: Automatically injects and configures the widget.
• ⚛️ React & Vue Support: Dedicated providers and hooks/composables.
• 🛠 AI Tools: Register client-side functions that the AI can execute (e.g., "Add to cart", "Change theme").
• 🧠 AI Context: Feed dynamic app state to the AI (e.g., "Current User", "Page Data").
• 🛡 Type Safe: Built with TypeScript and Zod.

Installation

npm install auraai-sdk zod
# or
yarn add auraai-sdk zod
# or
pnpm add auraai-sdk zod

Usage with React

1. Setup the Provider

Wrap your application with AuraProvider. This will initialize the widget.

// App.tsx
import { AuraProvider } from "auraai-sdk/react";

function App() {
  return (
    <AuraProvider
      config={{
        apiKey: "YOUR_API_KEY",
      }}
    >
      <YourApp />
    </AuraProvider>
  );
}

2. Registering Tools (Functions for AI) & Contexts (Dynamic App State)

Use the useTool hook to let the AI control your UI. Use the useAuraContext hook to feed dynamic app state to the AI.

import { useAuraContext, useTool } from "auraai-sdk/react";
import z from "zod";

const ProductsPage = () => {
  // Register a tool
  useTool({
    name: "addToCart",
    description: "Adds the current product to the shopping cart",
    displayContent: "Add {quantity} items to Cart",
    parameters: z.object({
      quantity: z.number().describe("Number of items to add"),
    }),
    execute: async ({ quantity }) => {
      console.log("Added", quantity, "items to cart");
      return { success: true, message: `Added ${quantity} items` };
    },
  });

  // Register a context
  useAuraContext("user", () =>
    JSON.stringify({
      name: "user",
      description: "User information",
      data: {
        name: "John Doe",
        age: 30,
        email: "[email protected]",
      },
    })
  );

  return <div>Product Details...</div>;
};

Usage with Vue 3

1. Setup the Plugin

// main.ts
import { createApp } from "vue";
import { createAura } from "auraai-sdk/vue";
import App from "./App.vue";

const app = createApp(App);

app.use(
  createAura({
    apiKey: "YOUR_API_KEY",
  })
);

app.mount("#app");

2. Registering Tools and Contexts

<script setup lang="ts">
import { useContext, useTool } from "auraai-sdk/vue";
import z from "zod";

// Register a tool
useTool({
  name: "alertUser",
  description: "Shows an alert to the user",
  displayContent: "Alert {message}",
  parameters: z.object({ message: z.string().describe("Message to show") }),
  execute: ({ message }) => {
    alert(message);
    return { success: true }; // You should return a value
  },
});

// Register a context
useContext("user", () =>
  JSON.stringify({
    name: "user",
    description: "User information",
    data: {
      name: "John Doe",
      age: 30,
      email: "[email protected]",
    },
  })
);
</script>

Usage with Vanilla JS

import { AuraClient } from "auraai-sdk";
import z from "zod";

// Initialize the chat widget
const client = new AuraClient({
  apiKey: "YOUR_API_KEY",
});

// Register a tool
client.registerTool({
  name: "alertUser",
  description: "Shows an alert to the user",
  displayContent: "Alert {message}",
  parameters: z.object({ message: z.string().describe("Message to show") }),
  execute: ({ message }) => {
    alert(message);
    return { success: true }; // You should return a value
  },
});

// Register a context
client.registerContext("user", () =>
  JSON.stringify({
    name: "user",
    description: "User information",
    data: {
      name: "John Doe",
      age: 30,
      email: "[email protected]",
    },
  })
);

Configuration

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | Required | Your project API Key from the Aura Dashboard. | | theme | 'light' | 'dark' | 'system' | 'system' | Sets the color scheme of the widget. | | locale | 'en' | 'fa' | 'en' | Sets the language of the UI. | | loadScript | boolean | true | If false, the SDK expects you to manually load the widget script. | | debug | boolean | false | Logs tool execution details to the console. |