React SDK Documentation - Swiftly AIKit

Installation

Install the React SDK via npm:

npm install swiftlyai-react

GitHub: Swiftly-Developed/SwiftlyAIKit-React-SDK

Quick Start

import { SwiftlyProvider, useChat, userMessage } from 'swiftlyai-react';

// Wrap your app with the provider
function App() {
  return (
    <SwiftlyProvider apiKey="sa_your_api_key">
      <ChatComponent />
    </SwiftlyProvider>
  );
}

// Use the chat hook
function ChatComponent() {
  const { data, isLoading, send } = useChat({
    model: 'claude-sonnet-4-5-20250929',
  });

  const handleSend = async () => {
    await send([userMessage('Hello!')]);
  };

  return <p>{data?.message}</p>;
}

SwiftlyProvider

Wrap your app or component tree with SwiftlyProvider to make the client available to all hooks:

<SwiftlyProvider
  apiKey="sa_your_api_key"
  bundleId="com.yourapp"  // optional
>
  {children}
</SwiftlyProvider>

useChat Hook

The primary hook for chat completions:

const {
  data,        // ChatResponse | null
  isLoading,   // boolean
  error,       // SwiftlyClientError | null
  send,        // (messages) => Promise<void>
  reset,       // () => void
} = useChat({
  model: 'claude-sonnet-4-5-20250929',
  options: {
    systemPrompt: 'You are a helpful assistant.',
    temperature: 0.7,
  },
});

// Send a message
await send([userMessage('Explain React hooks')]);

useStreamChat Hook

Stream responses in real-time with automatic state updates:

const {
  chunks,      // ChatResponse[]
  fullText,    // string (accumulated text)
  isStreaming, // boolean
  error,       // SwiftlyClientError | null
  send,        // (messages) => Promise<void>
  stop,        // () => void
} = useStreamChat({
  model: 'claude-sonnet-4-5-20250929',
});

await send([userMessage('Tell me a story')]);

useImageGeneration Hook

Generate images with a React hook:

const { data, isLoading, generate } = useImageGeneration({
  model: 'dall-e-3',
});

await generate('A sunset over the mountains');

// data?.images[0].url

Direct Client Usage

You can also use the SwiftlyClient directly without React hooks:

import { SwiftlyClient, userMessage } from 'swiftlyai-react';

const client = new SwiftlyClient({
  apiKey: 'sa_your_api_key',
});

const response = await client.chat(
  'claude-sonnet-4-5-20250929',
  [userMessage('Hello!')]
);

Error Handling

Errors are available through hook state or try/catch:

const { error, send } = useChat({ model: 'claude-sonnet-4-5-20250929' });

// Check error state
if (error) {
  console.log(error.message);
  console.log(error.code);

  if (error.isRetryable) {
    // Retry the request
  }
  if (error.isBillingError) {
    // Show upgrade prompt
  }
}

Quota Tracking

Monitor your usage quota from the provider context:

import { useSwiftly } from 'swiftlyai-react';

function QuotaDisplay() {
  const { quota } = useSwiftly();

  if (!quota) return null;

  return (
    <div>
      <p>Used: {quota.requestsUsed} / {quota.requestsLimit}</p>
      <p>{quota.usagePercent}%</p>
      {quota.isApproachingLimit && <span>Warning!</span>}
    </div>
  );
}