Secton SDK

A modern TypeScript SDK for the Secton API with intelligent streaming and conversation management.
Created by Supernova3339, now officially maintained by Secton.

Features

• Zero Dependencies - lightweight and tree-shakeable
• Intelligent Streaming - real-time response streaming with async iterators
• Conversation Management - built-in context management with multiple strategies
• Type Safety - full TypeScript support with comprehensive types
• Universal Compatibility - works in Node.js, browsers, and edge runtimes
• Smart Retry Logic - exponential backoff with jitter
• Token Management - accurate token estimation and context trimming

Installation

npm install secton

Quick Start

import { createClient } from 'secton';

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

// simple chat
const response = await client.ask('Hello, how are you?');
console.log(response);

// streaming chat
const stream = await client.chat.stream([
  { role: 'user', content: 'Tell me a story' }
]);

for await (const chunk of stream.stream) {
  process.stdout.write(chunk);
}

API Reference

Client Creation

import { createClient, configBuilder } from 'secton';

// direct configuration
const client = createClient({
  apiKey: 'your-api-key',
  baseURL: 'https://api.secton.org/v1',
  timeout: 30000,
  retries: 3
});

// builder pattern
const client = configBuilder()
  .apiKey('your-api-key')
  .timeout(60000)
  .debug(true)
  .build();

Chat Operations

// non-streaming chat
const result = await client.chat.chat([
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: 'What is TypeScript?' }
]);

console.log(result.message.content);

// streaming chat
const stream = await client.chat.stream([
  { role: 'user', content: 'Explain quantum computing' }
]);

// use async iterator
for await (const chunk of stream.stream) {
  console.log(chunk);
}

// or collect the full response
const collected = await stream.collect();
console.log(collected.message.content);

Conversation Management

// create a conversation
const conversation = client.conversations.create({
  title: 'My Chat',
  model: 'copilot-zero'
});

// add messages
client.conversations.addMessage(conversation.id, {
  role: 'user',
  content: 'Hello!'
});

// get messages with context management
const messages = client.conversations.getMessages(conversation.id);

// configure context strategy
client.conversations.updateConfig(conversation.id, {
  contextStrategy: 'priority',
  maxTokens: 2000
});

Models and Usage

// list available models
const models = await client.models.list();
console.log(models.models);

// get recommended models
const recommended = await client.models.getRecommended();

// check usage
const usage = await client.usage.get();
console.log(`Credits: ${usage.creditsAvailable}/${usage.creditsTotal}`);

// get usage alerts
const alerts = await client.usage.getAlerts();
alerts.forEach(alert => console.log(alert.message));

Advanced Streaming

// stream with callbacks
const stream = await client.chat.stream([
  { role: 'user', content: 'Count to 10' }
]);

stream.stream
  .onChunk(chunk => console.log('Chunk:', chunk))
  .onComplete(result => console.log('Done:', result.fullResponse))
  .onError(error => console.error('Error:', error));

// transform stream
import { mapStreamIterator } from 'secton';

const uppercaseStream = mapStreamIterator(
  stream.stream,
  chunk => chunk.toUpperCase()
);

for await (const chunk of uppercaseStream) {
  console.log(chunk);
}

Context Strategies

The SDK supports multiple context management strategies:

Sliding Window

Keeps the most recent messages within the token limit.

client.conversations.updateConfig(conversationId, {
  contextStrategy: 'sliding',
  maxTokens: 4000
});

Priority-based

Preserves important messages (system messages, recent interactions) longer.

client.conversations.updateConfig(conversationId, {
  contextStrategy: 'priority',
  maxTokens: 4000
});

Summarization

Compresses old context using the API while maintaining recent detail.

client.conversations.updateConfig(conversationId, {
  contextStrategy: 'summarization',
  maxTokens: 4000
});

Error Handling

import { 
  SectonError, 
  AuthenticationError, 
  RateLimitError,
  NetworkError 
} from 'secton';

try {
  const result = await client.chat.chat(messages);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else {
    console.error('Unknown error:', error);
  }
}

Environment Variables

The SDK automatically loads configuration from environment variables:

SECTON_API_KEY=your-api-key
SECTON_BASE_URL=https://api.secton.org/v1
SECTON_TIMEOUT=30000
SECTON_DEBUG=true

Conversation Serialization

// export conversation
const exported = client.conversations.export(conversationId, 'json');
fs.writeFileSync('conversation.json', exported);

// import conversation
const imported = fs.readFileSync('conversation.json', 'utf8');
const conversation = client.conversations.import(imported);

Examples

Simple Chatbot

import { createClient } from 'secton';

const client = createClient({
  apiKey: process.env.SECTON_API_KEY!
});

async function chatbot() {
  const conversation = client.conversations.create({
    title: 'Chatbot Session'
  });

  while (true) {
    const userInput = await getUserInput();
    if (userInput === 'quit') break;

    client.conversations.addMessage(conversation.id, {
      role: 'user',
      content: userInput
    });

    const messages = client.conversations.getMessages(conversation.id);
    const result = await client.chat.chat(messages);

    client.conversations.addMessage(conversation.id, result.message);
    console.log('Bot:', result.message.content);
  }
}

Streaming Chat with React

import React, { useState } from 'react';
import { createClient } from 'secton';

const client = createClient({
  apiKey: process.env.REACT_APP_SECTON_API_KEY!
});

function StreamingChat() {
  const [response, setResponse] = useState('');

  const handleSubmit = async (message: string) => {
    setResponse('');
    
    const stream = await client.chat.stream([
      { role: 'user', content: message }
    ]);

    for await (const chunk of stream.stream) {
      setResponse(prev => prev + chunk);
    }
  };

  return (
    <div>
      <div>{response}</div>
      {/* ui components */}
    </div>
  );
}

Browser Usage

<script type="module">
import { createClient } from 'https://unpkg.com/secton@latest/dist/index.esm.js';

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

const response = await client.ask('Hello from the browser!');
console.log(response);
</script>

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Support

• 🐛 Issue Tracker
• 💬 Discord Community
• 📧 Email Support