@synap/client

Type-safe Client SDK for Synap Core OS

A hybrid 3-layer SDK that provides both high-level convenience methods and low-level RPC access.

🏗️ Architecture

The SDK is built on 3 layers:

1. Core RPC (Auto-generated): Direct tRPC access via client.rpc.*
2. Business Facade: High-level methods via client.notes.*, client.chat.*, etc.
3. Authentication: Agnostic token management via getToken()

📦 Installation

npm install @synap/client
# or
pnpm add @synap/client
# or
yarn add @synap/client

🚀 Quick Start

Basic Usage

import SynapClient from '@synap/client';

const synap = new SynapClient({
  url: 'http://localhost:3000',
  getToken: async () => {
    // Get your auth token (Better Auth, custom auth, etc.)
    return await getSessionToken();
  },
});

// High-level API (recommended)
await synap.notes.create({
  content: '# My Note\n\nContent here',
  title: 'My Note',
});

// Low-level API (for power users)
await synap.rpc.notes.create.mutate({
  content: '# My Note',
});

With Static Token

const synap = new SynapClient({
  url: 'http://localhost:3000',
  token: 'your-static-token',
});

📚 API Reference

High-Level API (Business Facade)

Notes

// Create a note
await synap.notes.create({
  content: '# My Note',
  title: 'My Note',
  tags: ['important'],
});

// List notes
const notes = await synap.notes.list({
  limit: 20,
  offset: 0,
});

// Get a note
const note = await synap.notes.get('note-id');

Chat

// Send a message
const result = await synap.chat.sendMessage({
  content: 'Create a note about AI',
  threadId: 'thread-123',
});

// Get thread
const thread = await synap.chat.getThread('thread-123');

// List threads
const threads = await synap.chat.listThreads();

Tasks

// Complete a task
await synap.tasks.complete('task-id');

Capture

// Capture a thought
await synap.capture.thought('I need to remember to buy milk');

System

// Health check
const health = await synap.system.health();

// System info
const info = await synap.system.info();

Low-Level API (RPC)

For full control, use the RPC client directly:

// Direct tRPC access
await synap.rpc.notes.create.mutate({ content: '...' });
await synap.rpc.notes.list.query({ limit: 20 });
await synap.rpc.chat.sendMessage.mutate({ content: '...' });

🔌 Real-Time (WebSocket)

import { SynapRealtimeClient } from '@synap/client/realtime';

const realtime = new SynapRealtimeClient({
  url: synap.getRealtimeUrl('user-123'),
  userId: 'user-123',
  onMessage: (message) => {
    console.log('Received:', message);
    if (message.type === 'note.creation.completed') {
      // Refresh notes list
    }
  },
});

realtime.connect();

⚛️ React Integration

import { trpc, createSynapReactClient } from '@synap/client/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();
const trpcClient = createSynapReactClient({
  url: 'http://localhost:3000',
  getToken: async () => await getSessionToken(),
});

function App() {
  return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <MyComponent />
    </trpc.Provider>
  );
}

function MyComponent() {
  const { data: notes } = trpc.notes.list.useQuery();
  const createNote = trpc.notes.create.useMutation();

  return (
    <div>
      {notes?.map(note => (
        <div key={note.id}>{note.title}</div>
      ))}
    </div>
  );
}

🔐 Authentication

The SDK supports multiple authentication methods:

Better Auth (PostgreSQL mode)

const synap = new SynapClient({
  url: 'http://localhost:3000',
  getToken: async () => {
    const session = await getSession();
    return session?.token || null;
  },
});

Ory Kratos Session (PostgreSQL mode)

const synap = new SynapClient({
  url: 'http://localhost:3000',
  // Authentication handled via Ory Kratos session cookies
});

Custom Auth

const synap = new SynapClient({
  url: 'http://localhost:3000',
  getToken: async () => {
    // Your custom auth logic
    return await myAuthService.getToken();
  },
});

📖 Documentation

• Full Documentation - Complete guide
• Backend SDK Reference - Backend APIs
• Extensibility Guide - Extending the system

📝 License

MIT