NoFlow SDK

AI-powered chat SDK with customizable actions for web and mobile apps. Built with TypeScript and React.

✨ Features

• 🤖 AI-Powered Intent Detection - Uses OpenAI to understand user intent naturally
• 🎯 Customizable Actions - Define custom handlers for any action
• 📝 Smart Parameter Collection - Automatically asks for missing parameters
• 🎨 Themeable - Fully customizable appearance
• ⚛️ React Ready - Built with React and TypeScript
• 📱 Mobile Responsive - Works seamlessly on all devices
• ⌨️ Typing Animation - Smooth, natural typing effects
• 🔄 Async Support - Handles asynchronous operations out of the box

📦 Installation

npm install noflow-sdk

or

yarn add noflow-sdk

🚀 Quick Start

1. Set up your environment

Create a .env file and add your OpenAI API key:

OPENAI_API_KEY=your_openai_api_key_here

2. Basic Usage

import ChatSDK from "noflow-sdk";
import "noflow-sdk/dist/index.css"; // Import styles

function App() {
  return (
    <ChatSDK
      config={{
        title: "My Assistant",
        apiKey: process.env.OPENAI_API_KEY,
        intents: [
          {
            purpose: "greet user",
            handle: () => "Hello! How can I help you today?",
          },
        ],
      }}
    />
  );
}

3. Advanced Example with Parameters

import ChatSDK from "noflow-sdk";
import "noflow-sdk/dist/index.css";

function App() {
  const handlePasswordChange = async (params) => {
    const { oldPassword, newPassword } = params;

    // Your password change logic here
    const success = await changePassword(oldPassword, newPassword);

    return success
      ? "✅ Password changed successfully!"
      : "❌ Failed to change password. Please try again.";
  };

  const handleProfileUpdate = async (params) => {
    const { name, email } = params;
    await updateProfile({ name, email });
    return `Profile updated! Name: ${name}, Email: ${email}`;
  };

  return (
    <ChatSDK
      config={{
        title: "Rezto Assistant",
        apiKey: process.env.OPENAI_API_KEY,
        intents: [
          {
            purpose: "change password",
            paramsToExecute: [
              { oldPassword: "string" },
              { newPassword: "string" },
            ],
            handle: handlePasswordChange,
          },
          {
            purpose: "update profile",
            paramsToExecute: [{ name: "string" }, { email: "string" }],
            handle: handleProfileUpdate,
          },
          {
            purpose: "cancel subscription",
            handle: async () => {
              await cancelSubscription();
              return "Subscription cancelled successfully.";
            },
          },
        ],
        theme: {
          primaryColor: "#6366f1",
          secondaryColor: "#e0e7ff",
          avatar: "🤖",
          userAvatar: "👤",
        },
        welcomeMessage:
          "Hi! I'm your Rezto Assistant. How can I help you today?",
        fallbackMessage: "I'm not sure I understood that. Could you rephrase?",
      }}
    />
  );
}

📖 API Reference

ChatSDK Component

Props: ChatSDKProps<T>

| Prop | Type | Required | Description | | ------------------ | ---------------------------------------- | -------- | ------------------------------------------ | | config | ChatSDKConfig<T> | ✅ | Configuration object for the SDK | | isOpen | boolean | ❌ | Control widget open/close state externally | | onOpen | () => void | ❌ | Callback when widget opens | | onClose | () => void | ❌ | Callback when widget closes | | onIntentExecuted | (purpose: string, result: any) => void | ❌ | Callback when intent is executed | | onError | (error: Error) => void | ❌ | Callback for errors |

ChatSDKConfig<T>

| Property | Type | Required | Default | Description | | ----------------------- | ------------- | -------- | ------------------------------------ | ------------------------------ | | title | string | ❌ | "AI Assistant" | Chat widget title | | intents | Intent<T>[] | ✅ | - | Array of intent definitions | | apiKey | string | ✅ | - | OpenAI API key | | theme | Theme | ❌ | Default theme | Custom theme configuration | | placeholder | string | ❌ | "Type your message..." | Input placeholder | | welcomeMessage | string | ❌ | "Hello! How can I help you today?" | Initial message | | fallbackMessage | string | ❌ | Default fallback | Message when no intent matches | | enableTypingAnimation | boolean | ❌ | true | Enable typing animation | | openAIModel | string | ❌ | "gpt-4o-mini" | OpenAI model to use | | systemPrompt | string | ❌ | Default prompt | Custom system prompt | | maxHistoryLength | number | ❌ | 50 | Max messages in history |

Intent<T>

| Property | Type | Required | Description | | ----------------- | ----------------------------------------------------------- | -------- | -------------------------------------- | | purpose | string | ✅ | Natural language description of intent | | paramsToExecute | IntentParameter[] | ❌ | Required parameters | | handle | (params?: T) => void \| string \| Promise<void \| string> | ✅ | Handler function | | validateParams | (params: T) => boolean \| string | ❌ | Custom parameter validation |

Theme

| Property | Type | Default | Description | | ----------------- | -------- | ------------ | ----------------------- | | primaryColor | string | "#007bff" | Primary brand color | | secondaryColor | string | "#e3f2fd" | User message background | | backgroundColor | string | "#ffffff" | Widget background | | textColor | string | "#333333" | Text color | | fontFamily | string | System fonts | Font family | | borderRadius | string | "12px" | Border radius | | avatar | string | "🤖" | Assistant avatar | | userAvatar | string | "👤" | User avatar |

🎯 How It Works

1. Natural Language Understanding

Users can type naturally without selecting options:

• ❌ Old way: "Click 'Settings' → Click 'Password' → Fill form"
• ✅ NoFlow way: "I want to change my password"

2. Smart Parameter Collection

The SDK automatically detects missing parameters and asks for them:

User: "I want to change my password"
Bot: "To change password, I need the following information:
     • Old Password
     • New Password
     Please provide all of them."

User: "Old is 'pass123' and new is 'newpass456'"
Bot: "✅ Password changed successfully!"

3. Intent Detection

Uses OpenAI to match user messages to your defined intents with high accuracy.

💡 Examples

E-commerce Support

<ChatSDK
  config={{
    title: "Store Assistant",
    apiKey: process.env.OPENAI_API_KEY,
    intents: [
      {
        purpose: "track order",
        paramsToExecute: [{ orderNumber: "string" }],
        handle: async ({ orderNumber }) => {
          const status = await trackOrder(orderNumber);
          return `Order ${orderNumber} status: ${status}`;
        },
      },
      {
        purpose: "return item",
        paramsToExecute: [{ orderNumber: "string" }, { reason: "string" }],
        handle: async ({ orderNumber, reason }) => {
          await initiateReturn(orderNumber, reason);
          return "Return initiated! You'll receive a shipping label via email.";
        },
      },
    ],
  }}
/>

Customer Service

<ChatSDK
  config={{
    title: "Support Chat",
    apiKey: process.env.OPENAI_API_KEY,
    intents: [
      {
        purpose: "reset password",
        paramsToExecute: [{ email: "string" }],
        handle: async ({ email }) => {
          await sendPasswordResetEmail(email);
          return `Password reset link sent to ${email}`;
        },
      },
      {
        purpose: "update billing info",
        paramsToExecute: [
          { cardNumber: "string" },
          { expiryDate: "string" },
          { cvv: "string" },
        ],
        handle: async (params) => {
          await updateBilling(params);
          return "Billing information updated successfully!";
        },
        validateParams: (params) => {
          if (params.cvv.length !== 3) {
            return "CVV must be 3 digits";
          }
          return true;
        },
      },
    ],
  }}
/>

🎨 Theming

Customize the appearance to match your brand:

<ChatSDK
  config={{
    // ... other config
    theme: {
      primaryColor: "#8b5cf6",
      secondaryColor: "#f3e8ff",
      backgroundColor: "#ffffff",
      textColor: "#1f2937",
      fontFamily: "'Inter', sans-serif",
      borderRadius: "16px",
      avatar: "🦄",
      userAvatar: "😊",
    },
  }}
/>

🔧 Development

# Install dependencies
npm install

# Build the package
npm run build

# Watch mode for development
npm run dev

📝 TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type { ChatSDKConfig, Intent } from "noflow-sdk";

interface PasswordChangeParams {
  oldPassword: string;
  newPassword: string;
}

const config: ChatSDKConfig<PasswordChangeParams> = {
  title: "Assistant",
  apiKey: process.env.OPENAI_API_KEY!,
  intents: [
    {
      purpose: "change password",
      paramsToExecute: [{ oldPassword: "string" }, { newPassword: "string" }],
      handle: (params) => {
        // params is fully typed as PasswordChangeParams
        console.log(params.oldPassword);
        return "Success!";
      },
    },
  ],
};

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © datamucho

👤 Author

datamucho

• Email: [email protected]
• GitHub: @datamucho

🔗 Repository

https://github.com/datamucho/noflow-sdk

🐛 Issues

Found a bug? Please report it at: https://github.com/datamucho/noflow-sdk/issues

Made with ❤️ by datamucho