Naboo Embed SDK

A lightweight SDK for embedding the Naboo AI assistant in any web application. Works with vanilla JavaScript, React, and can be loaded via CDN.

Installation

npm install naboo-embed

or

yarn add naboo-embed

Usage

Vanilla JavaScript

import { NabooEmbedSDK } from "naboo-embed";

const naboo = new NabooEmbedSDK(document.getElementById("container"), {
  url: "https://app.naboo.ai",
  onReady: () => {
    // Send authentication tokens when ready
    naboo.sendTokens({
      sessionToken: "your-session-token",
      idToken: "your-id-token",
    });
  },
  onAuthError: (error) => {
    console.error("Authentication failed:", error);
  },
  onLogout: () => {
    console.log("User logged out");
  },
});

// Start a new chat
naboo.startNewChat();

// Send page context
naboo.setPageContext({
  parentUrl: window.location.href,
  title: document.title,
  content: document.body.innerText,
});

// Logout
naboo.logout();

// Clean up when done
naboo.destroy();

React

import { NabooEmbed, NabooEmbedRef } from "naboo-embed";
import { useRef, useEffect } from "react";

function App() {
  const nabooRef = useRef<NabooEmbedRef>(null);

  useEffect(() => {
    // Send tokens when component mounts
    nabooRef.current?.sendTokens({
      sessionToken: "your-session-token",
      idToken: "your-id-token",
    });
  }, []);

  return (
    <NabooEmbed
      ref={nabooRef}
      url="https://app.naboo.ai"
      onReady={() => console.log("Naboo is ready")}
      onAuthError={(error) => console.error("Auth error:", error)}
      onLogout={() => console.log("User logged out")}
      style={{ width: "100%", height: "100vh" }}
      className="naboo-container"
    />
  );
}

CDN (Browser)

<script src="https://unpkg.com/naboo-embed/dist/browser.global.js"></script>
<script>
  const naboo = new NabooEmbed.NabooEmbedSDK(
    document.getElementById("container"),
    {
      url: "https://app.naboo.ai",
      onReady: () => {
        naboo.sendTokens({
          sessionToken: "your-session-token",
          idToken: "your-id-token",
        });
      },
    }
  );
</script>

API Reference

NabooEmbedSDK

The vanilla JavaScript SDK class.

Constructor

new NabooEmbedSDK(container: HTMLElement, config: NabooEmbedConfig)

Parameters:

• container: The HTML element where the iframe will be inserted
• config: Configuration object (see NabooEmbedConfig below)

Methods

• sendTokens(tokens: { sessionToken: string; idToken: string }): Send authentication tokens to the iframe
• startNewChat(): Start a new chat session
• setPageContext(context?: PageContext): Send page context information
• logout(): Request logout from the iframe
• getIframe(): Get the iframe element
• destroy(): Clean up event listeners and remove the iframe

NabooEmbed (React Component)

React component wrapper for the SDK.

Props

interface NabooEmbedProps extends NabooEmbedConfig {
  style?: React.CSSProperties;
  className?: string;
}

Ref Methods

Access via ref.current:

• sendTokens(tokens: { sessionToken: string; idToken: string })
• startNewChat()
• setPageContext(context?: PageContext)
• logout()
• getIframe(): HTMLIFrameElement | null

NabooEmbedConfig

interface NabooEmbedConfig {
  /** URL to the Naboo app */
  url: string;

  /** Called when iframe is ready to receive messages */
  onReady?: () => void;

  /** Called when user logs out from within the iframe */
  onLogout?: () => void;

  /** Called when authentication fails (e.g., invalid/expired token) */
  onAuthError?: (error: string) => void;

  /** Theme preference: 'dark', 'light', 'system' (follows OS preference), or undefined (same as 'system') */
  theme?: "dark" | "light" | "system";
}

PageContext

interface PageContext {
  /** The parent page's URL */
  parentUrl: string;
  /** Page title */
  title?: string;
  /** Page content (main text content) */
  content?: string;
}

TypeScript Support

This package is written in TypeScript and includes full type definitions. All types are exported for your convenience:

import type {
  NabooEmbedConfig,
  NabooEmbedAPI,
  PageContext,
  ParentToIframeMessage,
  IframeToParentMessage,
  NabooAuthMessage,
  NabooNewChatMessage,
  NabooPageContextMessage,
  NabooLogoutMessage,
} from "naboo-embed";

Message Validation

The SDK includes Zod schemas for message validation:

import {
  PageContextSchema,
  NabooAuthMessageSchema,
  NabooNewChatMessageSchema,
  NabooPageContextMessageSchema,
  NabooLogoutMessageSchema,
  ParentToIframeMessageSchema,
  NabooReadyMessageSchema,
  NabooIframeLogoutMessageSchema,
  NabooAuthErrorMessageSchema,
  IframeToParentMessageSchema,
} from "naboo-embed";

Security

• All messages are validated using Zod schemas
• PostMessage communication is restricted to the configured origin
• Messages are queued until the iframe is ready to prevent message loss

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

# Development mode with watch
npm run dev

Publishing

To publish a new version to npm:

# Make sure you're logged into npm first
npm login

# Publish a patch version (0.1.0 -> 0.1.1)
npm run publish:patch

# Publish a minor version (0.1.0 -> 0.2.0)
npm run publish:minor

# Publish a major version (0.1.0 -> 1.0.0)
npm run publish:major

# Test the publish process without actually publishing
npm run publish:dry-run

The publish script will:

1. ✅ Check that you're logged into npm
2. 📦 Build the package
3. 📝 Bump the version in package.json
4. 📤 Publish to npm

Note: The script uses --no-git-tag-version so it won't create git tags automatically. You can create tags manually if needed.

License

MIT

Links

• Homepage
• GitHub Repository