JavaScript SDK

The Connix JavaScript SDK provides a modern, type-safe way to integrate Connix services into your web applications, Node.js backends, and serverless functions. Built with TypeScript-first design and modern JavaScript patterns.

Installation

Install the Connix JavaScript SDK using npm, yarn, pnpm, or bun:

npm install @connix/sdk
# or
yarn add @connix/sdk
# or
pnpm add @connix/sdk
# or
bun add @connix/sdk

Quick Start

Node.js / Server-side

import { ConnixClient } from '@connix/sdk';

// Initialize the client
const client = new ConnixClient({
  apiKey: 'your-api-key-here'
});

// Create a project and launch an agent
async function main() {
  try {
    // Create a new project
    const project = await client.createProject({
      name: 'web-scraper-project'
    });

    console.log(`✅ Created project: ${project.name} (ID: ${project.id})`);

    // Launch an agent
    const agent = await client.launchAgent({
      name: 'data-extractor',
      projectId: project.id
    });

    console.log(`🚀 Agent launched: ${agent.message}`);

  } catch (error) {
    console.error('Error:', error);
  }
}

main();

Browser / Client-side

<!DOCTYPE html>
<html>
<head>
  <title>Connix Web App</title>
</head>
<body>
  <script type="module">
    import { ConnixClient } from 'https://unpkg.com/@connix/sdk@latest/dist/browser.js';

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

    async function loadProjects() {
      try {
        const projects = await client.listProjects();
        console.log('Projects:', projects);
      } catch (error) {
        console.error('Failed to load projects:', error);
      }
    }

    loadProjects();
  </script>
</body>
</html>

TypeScript Support

The SDK is written in TypeScript and provides full type safety out of the box:

import { ConnixClient, Project, LaunchAgentRequest } from '@connix/sdk';

const client = new ConnixClient({
  apiKey: process.env.CONNIX_API_KEY!
});

async function buildAIWorkflow(): Promise<void> {
  // Type-safe project creation
  const project: Project = await client.createProject({
    name: 'ml-model-training'
  });

  // Type-safe agent launching
  const agentRequest: LaunchAgentRequest = {
    name: 'model-trainer',
    projectId: project.id
  };

  const response = await client.launchAgent(agentRequest);
  console.log(`Agent status: ${response.message}`);
}

Authentication

API Key Authentication

// Direct API key
const client = new ConnixClient({
  apiKey: 'cx_1234567890abcdef'
});

// Environment variable (recommended)
const client = new ConnixClient({
  apiKey: process.env.CONNIX_API_KEY
});

// Auto-detection from environment
const client = new ConnixClient(); // Looks for CONNIX_API_KEY

OAuth2 (Browser Applications)

const client = new ConnixClient({
  auth: {
    type: 'oauth2',
    clientId: 'your-client-id',
    redirectUri: 'https://yourapp.com/callback'
  }
});

// Initiate OAuth flow
const authUrl = client.getAuthorizationUrl(['read', 'write']);
window.location.href = authUrl;

// Handle callback
const token = await client.exchangeCodeForToken(authCode);

Working with Projects

// List all projects
const projects = await client.listProjects();
console.log(`Found ${projects.projects.length} projects`);

// Create a new project
const newProject = await client.createProject({
  name: 'ai-content-generator'
});

// Project details
projects.projects.forEach(project => {
  console.log(`Project: ${project.name} (ID: ${project.id})`);
});

Agent Management

// Launch an agent with specific configuration
const agent = await client.launchAgent({
  name: 'content-writer',
  projectId: newProject.id
});

console.log(`Agent launched: ${agent.message}`);

Configuration Options

Customize the client with comprehensive configuration:

const client = new ConnixClient({
  apiKey: 'your-api-key',

  // API Configuration
  baseURL: 'https://api.connix.io',
  timeout: 30000,
  retries: 3,

  // Request Configuration
  headers: {
    'User-Agent': 'MyApp/1.0.0',
    'X-Custom-Header': 'value'
  },

  // Development Options
  debug: process.env.NODE_ENV === 'development',

  // Rate Limiting
  rateLimitStrategy: 'exponential-backoff'
});

Error Handling

The SDK provides comprehensive error handling with specific error types:

import { ConnixError, APIError, NetworkError, RateLimitError } from '@connix/sdk';

try {
  const project = await client.createProject({ name: 'test' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after: ${error.retryAfter}ms`);

    // Automatic retry with backoff
    await new Promise(resolve => setTimeout(resolve, error.retryAfter));
    // Retry the request...

  } else if (error instanceof APIError) {
    switch (error.status) {
      case 401:
        console.error('Invalid API key');
        break;
      case 403:
        console.error('Insufficient permissions');
        break;
      case 404:
        console.error('Resource not found');
        break;
      default:
        console.error(`API error: ${error.message}`);
    }
  } else if (error instanceof NetworkError) {
    console.error('Network error - check your connection');
  } else {
    console.error('Unexpected error:', error);
  }
}

Framework Integrations

React

import { useState, useEffect } from 'react';
import { ConnixClient } from '@connix/sdk';

const client = new ConnixClient({
  apiKey: process.env.REACT_APP_CONNIX_API_KEY
});

function ProjectList() {
  const [projects, setProjects] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadProjects() {
      try {
        const response = await client.listProjects();
        setProjects(response.projects);
      } catch (error) {
        console.error('Failed to load projects:', error);
      } finally {
        setLoading(false);
      }
    }

    loadProjects();
  }, []);

  if (loading) return <div>Loading projects...</div>;

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

Express.js

import express from 'express';
import { ConnixClient } from '@connix/sdk';

const app = express();
const client = new ConnixClient();

app.use(express.json());

app.post('/api/projects', async (req, res) => {
  try {
    const project = await client.createProject({
      name: req.body.name
    });
    res.json(project);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

API Reference

Client Constructor

new ConnixClient(options?: ClientOptions)

Methods

Projects

createProject(request: CreateProjectRequest): Promise<Project>
listProjects(): Promise<ListProjectsResponse>

Agents

launchAgent(request: LaunchAgentRequest): Promise<LaunchAgentResponse>

Utilities

hello(name: string): Promise<HelloResponse>

Types

interface Project {
  id: number;
  name: string;
}

interface CreateProjectRequest {
  name: string;
}

interface LaunchAgentRequest {
  name: string;
  projectId: number;
}

interface ClientOptions {
  apiKey?: string;
  baseURL?: string;
  timeout?: number;
  retries?: number;
  headers?: Record<string, string>;
  debug?: boolean;
}

Examples Repository

Explore our comprehensive examples covering:

Web Applications: React, Vue, Angular integrations
Server Applications: Express, Fastify, Next.js backends
Serverless: AWS Lambda, Vercel, Netlify functions
Mobile: React Native and Expo applications

Visit github.com/connix-io/connix-js-examples

Community & Support

Documentation: docs.connix.io
GitHub: github.com/connix-io/connix-js
NPM: @connix/sdk
Discord: Join our community
Email: engineering@connix.io