AINative TypeScript/JavaScript SDK

Official TypeScript/JavaScript SDK for AINative Studio: ZeroDB vector database, Agent Swarm orchestration, and x402 agent payments (HTTP 402 USDC micropayments) in one client. Built for AI agents, MCP servers, and vibe-coded apps that need agents to pay for things autonomously.

🚀 Features

TypeScript Support - Full type safety with comprehensive TypeScript definitions
Browser & Node.js - Works in both browser and server environments
Framework Integrations - React hooks and Vue composables included
x402 Agent Payments - Typed client + WWW-Authenticate: Payment header parser for HTTP 402 USDC micropayments between agents
Auto-retry & Error Handling - Built-in retry logic and comprehensive error types
Tree-shakeable - Only import what you need for optimal bundle size
Real-time Streaming - Server-Sent Events support for live updates
Modern Architecture - Built with modern JavaScript features and best practices

📦 Installation

# npm
npm install @ainative/sdk

# yarn
yarn add @ainative/sdk

# pnpm
pnpm add @ainative/sdk

🔧 Quick Start

import { AINativeClient } from '@ainative/sdk';

// Initialize the client
const client = new AINativeClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.ainative.studio' // optional
});

// Create a project
const project = await client.zerodb.projects.create({
  name: 'My AI Project',
  description: 'Vector storage for my AI application'
});

// Store vectors
await client.zerodb.vectors.upsert(project.data.id, {
  vectorEmbedding: [0.1, 0.2, 0.3, 0.4],
  metadata: { title: 'Document 1', category: 'tutorial' },
  namespace: 'documents'
});

// Search vectors
const results = await client.zerodb.vectors.search(project.data.id, {
  queryVector: [0.1, 0.2, 0.3, 0.4],
  topK: 5,
  namespace: 'documents'
});

console.log('Found vectors:', results.data.vectors);

🎯 React Integration

import React from 'react';
import { AINativeProvider, useZeroDB } from '@ainative/sdk/react';

function App() {
  return (
    <AINativeProvider config={{ apiKey: 'your-api-key' }}>
      <ProjectList />
    </AINativeProvider>
  );
}

function ProjectList() {
  const { projects, loading, error } = useZeroDB();
  const [projectList, setProjectList] = React.useState([]);

  React.useEffect(() => {
    async function loadProjects() {
      const response = await projects.list();
      setProjectList(response.data);
    }
    loadProjects();
  }, []);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {projectList.map(project => (
        <li key={project.id}>{project.name}</li>
      ))}
    </ul>
  );
}

🌟 Vue.js Integration

<template>
  <div>
    <div v-if="loading">Loading...</div>
    <div v-else-if="error">Error: {{ error.message }}</div>
    <ul v-else>
      <li v-for="project in projectList" :key="project.id">
        {{ project.name }}
      </li>
    </ul>
    <button @click="createProject">Create Project</button>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { useZeroDB } from '@ainative/sdk/vue';

const { projects, loading, error } = useZeroDB({
  apiKey: 'your-api-key'
});

const projectList = ref([]);

onMounted(async () => {
  const response = await projects.list();
  projectList.value = response.data;
});

async function createProject() {
  await projects.create({
    name: 'New Project',
    description: 'Created from Vue app'
  });
  // Reload projects
  const response = await projects.list();
  projectList.value = response.data;
}
</script>

📚 API Reference

Client Configuration

interface ClientConfig {
  apiKey?: string;           // Your AINative API key
  baseUrl?: string;          // API base URL (default: https://api.ainative.studio)
  organizationId?: string;   // Organization ID for multi-tenant scenarios
  timeout?: number;          // Request timeout in ms (default: 30000)
  maxRetries?: number;       // Max retry attempts (default: 3)
  retryDelay?: number;       // Retry delay in ms (default: 1000)
  debug?: boolean;           // Enable debug logging (default: false)
  headers?: object;          // Custom headers for all requests
}

ZeroDB Operations

Projects

// List projects
const projects = await client.zerodb.projects.list({ limit: 10 });

// Create project
const project = await client.zerodb.projects.create({
  name: 'Project Name',
  description: 'Project description',
  type: 'development' // or 'production'
});

// Get project
const project = await client.zerodb.projects.get('project-id');

// Update project
const updated = await client.zerodb.projects.update('project-id', {
  name: 'New Name',
  status: 'active'
});

// Delete project
await client.zerodb.projects.delete('project-id');

Vector Operations

// Upsert vector
const vector = await client.zerodb.vectors.upsert('project-id', {
  vectorEmbedding: [0.1, 0.2, 0.3, 0.4],
  metadata: { title: 'Document', category: 'tutorial' },
  namespace: 'documents',
  document: 'Text content of the document'
});

// Search vectors
const results = await client.zerodb.vectors.search('project-id', {
  queryVector: [0.1, 0.2, 0.3, 0.4],
  namespace: 'documents',
  topK: 5,
  similarityThreshold: 0.7
});

// Batch upsert
await client.zerodb.vectors.batchUpsert('project-id', {
  vectors: [
    { vectorEmbedding: [0.1, 0.2], metadata: { id: 1 } },
    { vectorEmbedding: [0.3, 0.4], metadata: { id: 2 } }
  ]
});

// List vectors
const vectors = await client.zerodb.vectors.list('project-id', 'namespace', 10);

Memory Operations

// Store memory
const memory = await client.zerodb.memory.store('project-id', {
  content: 'User asked about vector search',
  agentId: '550e8400-e29b-41d4-a716-446655440000',
  sessionId: '123e4567-e89b-12d3-a456-426614174000',
  role: 'user',
  memoryMetadata: { topic: 'vector_search', priority: 'high' }
});

// Search memories
const memories = await client.zerodb.memory.search('project-id', {
  query: 'vector search',
  sessionId: '123e4567-e89b-12d3-a456-426614174000',
  limit: 10
});

// List memories
const allMemories = await client.zerodb.memory.list('project-id', { limit: 50 });

Event Streaming

// Publish event
const event = await client.zerodb.events.publish('project-id', {
  topic: 'user_actions',
  eventPayload: {
    action: 'login',
    userId: 'user-123',
    timestamp: new Date().toISOString()
  }
});

// List events
const events = await client.zerodb.events.list('project-id', 'user_actions', 100);

// Stream events (real-time)
const eventSource = client.zerodb.events.stream('project-id', {
  topic: 'user_actions',
  onMessage: (event) => {
    console.log('New event:', event);
  },
  onError: (error) => {
    console.error('Stream error:', error);
  },
  onConnect: () => {
    console.log('Connected to event stream');
  }
});

// Stop streaming
eventSource.close();

Agent Swarm Operations

Swarm Management

// Start agent swarm
const swarm = await client.agentSwarm.swarm.start({
  projectId: 'project-id',
  name: 'Data Analysis Swarm',
  agents: [
    { type: 'data_analyst', config: { specialization: 'customer_data' } },
    { type: 'report_generator', config: { format: 'markdown' } }
  ],
  orchestration: {
    maxAgents: 5,
    coordinationModel: 'hierarchical'
  }
});

// Check swarm status
const status = await client.agentSwarm.swarm.status('swarm-id');

// Stop swarm
await client.agentSwarm.swarm.stop('swarm-id');

Task Orchestration

// Orchestrate task
const task = await client.agentSwarm.tasks.orchestrate({
  swarmId: 'swarm-id',
  task: 'Analyze customer feedback and generate insights report',
  priority: 'high',
  context: { dataSource: 'customer_surveys' }
});

// Check task status
const taskStatus = await client.agentSwarm.tasks.status('task-id');

// List swarm tasks
const tasks = await client.agentSwarm.tasks.list('swarm-id');

x402 Agent Payments

x402 is the HTTP 402 "Payment Required" micropayment standard — an agent hits a paid endpoint, gets a 402 back with payment requirements, pays in USDC, and retries. client.x402 is a typed wrapper around AINative's x402 subscription endpoints, so you don't parse the WWW-Authenticate: Payment header or the raw 402 body yourself.

import { AINativeClient, X402PaymentRequiredError } from '@ainative/sdk';

const client = new AINativeClient({ apiKey: 'your-api-key' });

// Shop first — no payment required to see what's available
const { data } = await client.x402.listPlans();
console.log(data.plans); // [{ id, price_usd, amount, asset, network, pay_to }, ...]

try {
  // Attempt to subscribe without proof of payment
  await client.x402.subscribe({ plan_id: 'pro' });
} catch (error) {
  if (error instanceof X402PaymentRequiredError) {
    // error.requirements is already parsed from the real 402 challenge:
    // { scheme, network, asset, amount, pay_to }
    const proof = await payWithYourWallet(error.requirements);

    // Retry with proof — resolves normally this time
    const subscription = await client.x402.subscribe({
      plan_id: 'pro',
      payment_proof: proof,
    });
  }
}

Also exported standalone, if you just need to parse a raw WWW-Authenticate: Payment header yourself:

import { parseX402PaymentHeader } from '@ainative/sdk';

const requirements = parseX402PaymentHeader(response.headers.get('www-authenticate'));
// { scheme: 'exact', network: 'circle', asset: 'USDC', amount: '5.00', pay_to: '0x...' }

Error Handling

import { 
  AINativeError, 
  NetworkError, 
  AuthenticationError, 
  RateLimitError 
} from '@ainative/sdk';

try {
  const result = await client.zerodb.projects.list();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
    // Redirect to login
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter);
    // Wait and retry
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
    // Check connection
  } else if (error instanceof AINativeError) {
    console.error('API error:', error.message, 'Status:', error.status);
  } else {
    console.error('Unexpected error:', error);
  }
}

🎨 Framework Examples

Next.js App Router

// app/api/projects/route.ts
import { AINativeClient } from '@ainative/sdk';

const client = new AINativeClient({
  apiKey: process.env.AINATIVE_API_KEY!
});

export async function GET() {
  try {
    const projects = await client.zerodb.projects.list();
    return Response.json(projects.data);
  } catch (error) {
    return Response.json({ error: 'Failed to fetch projects' }, { status: 500 });
  }
}

Express.js Server

import express from 'express';
import { AINativeClient } from '@ainative/sdk';

const app = express();
const client = new AINativeClient({
  apiKey: process.env.AINATIVE_API_KEY!
});

app.get('/api/projects', async (req, res) => {
  try {
    const projects = await client.zerodb.projects.list();
    res.json(projects.data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

🛠️ Development

# Clone the repository
git clone https://github.com/ainative/ainative-sdk-js.git
cd ainative-sdk-js

# Install dependencies
npm install

# Build the SDK
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Type check
npm run type-check

📝 Contributing

We welcome contributions! Please read our Contributing Guide to get started.

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run tests: npm test
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

📞 Support

📧 Email: support@ainative.studio
💬 Discord: Join our community
🐛 Issues: GitHub Issues
📖 Docs: Documentation

Made with ❤️ by the AINative team

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs/reports		docs/reports
examples		examples
src		src
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
test-build.js		test-build.js
tsconfig.json		tsconfig.json

Navigation Menu

Repository navigation

About

Repository files navigation

AINative TypeScript/JavaScript SDK

🚀 Features

📦 Installation

🔧 Quick Start

🎯 React Integration

🌟 Vue.js Integration

📚 API Reference

Client Configuration

ZeroDB Operations

Projects

Vector Operations

Memory Operations

Event Streaming

Agent Swarm Operations

Swarm Management

Task Orchestration

x402 Agent Payments

Error Handling

🎨 Framework Examples

Next.js App Router

Express.js Server

🛠️ Development

📝 Contributing

📄 License

🔗 Links

📞 Support

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AINative TypeScript/JavaScript SDK

🚀 Features

📦 Installation

🔧 Quick Start

🎯 React Integration

🌟 Vue.js Integration

📚 API Reference

Client Configuration

ZeroDB Operations

Projects

Vector Operations

Memory Operations

Event Streaming

Agent Swarm Operations

Swarm Management

Task Orchestration

x402 Agent Payments

Error Handling

🎨 Framework Examples

Next.js App Router

Express.js Server

🛠️ Development

📝 Contributing

📄 License

🔗 Links

📞 Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages