Typescript

A comprehensive TypeScript SDK for interacting with the Neura AI API, with built-in React components.

Features

• 🚀 Full TypeScript Support: Complete type definitions for all API interactions

• 🔄 Streaming Support: Real-time streaming of AI responses

• ⚛️ React Components: Ready-to-use React components for quick integration

• 🔒 Retry Logic: Automatic retries for failed requests

• 🚦 Rate Limiting: Built-in throttling to respect API limits

• 💾 Caching: Optional response caching to improve performance

• 📁 File Handling: Support for sending files to the API

Installation

npm install neura-sdk

Basic Usage

Initialize the SDK

import { NeuraSDK } from 'neura-sdk';

const neura = new NeuraSDK({
  baseUrl: 'https://api.example.com',
  apiKey: 'your-api-key',
  // Optional configuration
  maxRetries: 3,
  retryDelay: 1000,
  requestsPerMinute: 60,
  enableCache: true,
  cacheTTL: 5 * 60 * 1000, // 5 minutes
});

Create a Completion (Non-streaming)

const response = await neura.createCompletion({
  messages: JSON.stringify([
    { role: 'user', content: 'Hello, how are you?' }
  ]),
  // Optional parameters
  sessionId: 'session-123',
  userId: 'user-456',
  reasoningFormat: 'json',
});

console.log(response);

Create a Streaming Completion

const stream = neura.createCompletionStream({
  messages: JSON.stringify([
    { role: 'user', content: 'Tell me a story' }
  ]),
});

let fullResponse = '';

stream.on('chunk', (chunk) => {
  console.log('Received chunk:', chunk);
  fullResponse += chunk.chunk;
});

stream.on('done', () => {
  console.log('Stream complete');
  console.log('Full response:', fullResponse);
});

stream.on('error', (error) => {
  console.error('Stream error:', error);
});

React Components

Provider Setup

Wrap your application with the NeuraProvider:

import { NeuraProvider } from 'neura-sdk';

function App() {
  return (
    <NeuraProvider 
      config={{
        baseUrl: 'https://api.example.com',
        apiKey: 'your-api-key',
      }}
    >
      <YourApp />
    </NeuraProvider>
  );
}

Using the Completion Component

import { NeuraCompletion } from 'neura-sdk';

function CompletionExample() {
  return (
    <NeuraCompletion
      options={{
        messages: JSON.stringify([
          { role: 'user', content: 'What is the capital of France?' }
        ]),
      }}
    >
      {({ response, loading, error, refetch }) => (
        <div>
          {loading && <p>Loading...</p>}
          {error && <p>Error: {error.message}</p>}
          {response && !('error' in response) && (
            <div>
              <h3>Response:</h3>
              <p>{response.response}</p>
              <button onClick={refetch}>Refresh</button>
            </div>
          )}
        </div>
      )}
    </NeuraCompletion>
  );
}

Using the Stream Component

import { NeuraStream } from 'neura-sdk';

function StreamExample() {
  return (
    <NeuraStream
      options={{
        messages: JSON.stringify([
          { role: 'user', content: 'Write a short poem about coding' }
        ]),
      }}
    >
      {({ fullText, loading, error, restart }) => (
        <div>
          {loading && <p>Streaming...</p>}
          {error && <p>Error: {error.message}</p>}
          <div className="response">
            {fullText || 'Waiting for response...'}
          </div>
          <button onClick={restart} disabled={loading}>
            Restart
          </button>
        </div>
      )}
    </NeuraStream>
  );
}

Using the Chat Component

import { NeuraChat } from 'neura-sdk';

function ChatExample() {
  return (
    <NeuraChat
      sessionId="user-session-123"
      userId="user-456"
      initialMessages={[
        { role: 'system', content: 'You are a helpful assistant.' }
      ]}
      // Optional custom renderers
      renderMessage={(message, index) => (
        <div key={index} className={`custom-message ${message.role}`}>
          <strong>{message.role}:</strong> {message.content}
        </div>
      )}
    />
  );
}

Advanced Usage

Sending File Data

// Using a base64 string
const response = await neura.createCompletion({
  messages: JSON.stringify([{ role: 'user', content: 'Analyze this file' }]),
  fileData: 'base64EncodedString',
});

// Or using a Buffer
import { readFileSync } from 'fs';
const fileBuffer = readFileSync('path/to/file');

const response = await neura.createCompletion({
  messages: JSON.stringify([{ role: 'user', content: 'Analyze this file' }]),
  fileData: fileBuffer,
});

Clearing the Cache

// Clear the entire cache
neura.clearCache();

Error Handling

The SDK provides detailed error information for both API errors and client-side errors.

try {
  const response = await neura.createCompletion({
    messages: JSON.stringify([{ role: 'user', content: 'Hello' }]),
  });
  
  // Check if the response is an error
  if ('error' in response) {
    console.error('API error:', response.error);
    console.error('Error code:', response.code);
  } else {
    console.log('Success:', response.response);
  }
} catch (error) {
  console.error('Client error:', error);
}

API Reference

NeuraSDK

Constructor

new NeuraSDK(config: NeuraSDKConfig)

Methods

createCompletion

createCompletion(options: CompletionsRequestOptions): Promise<NeuraResponse>

createCompletionStream

createCompletionStream(options: CompletionsRequestOptions): NeuraStream

clearCache

clearCache(): void

React Components

NeuraProvider

<NeuraProvider config={NeuraSDKConfig}>
  {children}
</NeuraProvider>

useNeura Hook

const { sdk } = useNeura();

NeuraCompletion

<NeuraCompletion
  options={CompletionsRequestOptions}
  onSuccess={(response) => void}
  onError={(error) => void}
>
  {({ response, loading, error, refetch }) => ReactNode}
</NeuraCompletion>

NeuraStream

<NeuraStream
  options={CompletionsRequestOptions}
  onChunk={(chunk) => void}
  onComplete={(fullText) => void}
  onError={(error) => void}
>
  {({ chunks, fullText, loading, error, restart }) => ReactNode}
</NeuraStream>

NeuraChat

<NeuraChat
  sessionId={string}
  userId={string}
  initialMessages={Message[]}
  reasoningFormat={string}
  onNewMessage={(message) => void}
  renderMessage={(message, index) => ReactNode}
  renderInput={(props) => ReactNode}
/>

License

MIT

Let's create a CONTRIBUTING.md file:

```js project="Neura SDK" file="CONTRIBUTING.md" type="nodejs"
# Contributing to Neura SDK

Thank you for your interest in contributing to Neura SDK! This document provides guidelines and instructions for contributing.

## Code of Conduct

Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).

## How Can I Contribute?

### Reporting Bugs

- Check if the bug has already been reported in the Issues section
- Use the bug report template when creating a new issue
- Include detailed steps to reproduce the bug
- Include screenshots if applicable
- Specify the version of the SDK you're using

### Suggesting Enhancements

- Check if the enhancement has already been suggested in the Issues section
- Use the feature request template when creating a new issue
- Provide a clear description of the enhancement
- Explain why this enhancement would be useful

### Pull Requests

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Make your changes
4. Run tests to ensure your changes don't break existing functionality
5. Submit a pull request

## Development Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/neura-sdk.git
   cd neura-sdk

1. Install dependencies:

npm install

1. Build the project:

npm run build

1. Run tests:

npm test

Coding Guidelines

• Follow the existing code style

• Write tests for new features

• Update documentation for any changes

• Keep pull requests focused on a single feature or bug fix

Commit Messages

• Use the present tense ("Add feature" not "Added feature")

• Use the imperative mood ("Move cursor to..." not "Moves cursor to...")

• Reference issues and pull requests liberally after the first line

Documentation

• Update the README.md with details of changes to the interface

• Update the API documentation for any changed functionality

• Add examples for new features

Testing

• Write tests for new features

• Ensure all tests pass before submitting a pull request

• Aim for high test coverage

Versioning

We use SemVer for versioning:

• MAJOR version for incompatible API changes

• MINOR version for backwards-compatible functionality

• PATCH version for backwards-compatible bug fixes

License

By contributing to Neura SDK, you agree that your contributions will be licensed under the project's MIT License.

Copyright (c) 2025 Neura AI

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information: https://opensource.org/licenses/MIT