@shogo-ai/sdk weekly downloads statistics

@shogo-ai/sdk

The Shogo client SDK — auth, typed database access, and the LLM gateway. Voice, email, agent-runtime, db adapters, and CLI helpers ship as separate @shogo-ai/* packages but remain importable via deprecated subpath shims here through v1.x. See MIGRATION.md.

Installation

npm install @shogo-ai/sdk
# or
bun add @shogo-ai/sdk

Package family

The SDK was split in v1.6 into focused packages. All seven release in lockstep on the sdk-v* tag:

Package	Use when
@shogo-ai/sdk	Building a client (web / RN / Node consumer)
@shogo-ai/core	Server primitives — logger, OTEL, streaming, chat-message
@shogo-ai/agent	Building an agent backend on pi-ai / pi-agent-core
@shogo-ai/db	Prisma adapter wiring (PG / SQLite / libSQL)
@shogo-ai/email	Transactional email (SES / SMTP / OCI)
@shogo-ai/voice	ElevenLabs + Twilio voice infra + React/RN UI
@shogo-ai/cli	Deploy / manifest / packager helpers

Old @shogo-ai/sdk/<subpath> imports keep working through back-compat re-export shims. New code should import from the corresponding package directly. See MIGRATION.md for the full subpath → package map.

Quick Start

import { createClient } from '@shogo-ai/sdk'

const client = createClient({
  apiUrl: 'http://localhost:3000',
})

// Authentication
await client.auth.signUp({ email: 'user@example.com', password: 'secret' })
await client.auth.signIn({ email: 'user@example.com', password: 'secret' })
const user = client.auth.currentUser()

// Database operations
const todos = await client.db.todos.list({ where: { completed: false } })
const todo = await client.db.todos.create({ title: 'Buy milk' })
await client.db.todos.update(todo.id, { completed: true })
await client.db.todos.delete(todo.id)

Features

Feature	Lives in
Authentication — email/password with Better Auth	@shogo-ai/sdk (client.auth)
Database client — MongoDB-style CRUD with client.db.<resource>	@shogo-ai/sdk (client.db)
LLM Gateway — drop-in Vercel AI SDK provider	@shogo-ai/sdk (client.llm)
Machines & external triggers — pair desktops + VPS workers, pin projects for webhooks	@shogo-ai/sdk (client.machines)
Project clone / sync — pull a project's workspace cloud→local, push edits back	@shogo-ai/sdk (client.projects)
Memory — SQLite FTS5 + TF-IDF over per-user markdown	@shogo-ai/sdk/memory
Voice — ElevenLabs convai proxy + React hooks	@shogo-ai/voice (also as @shogo-ai/sdk/voice/*)
Email — SMTP / SES / OCI providers + templates	@shogo-ai/email (also as @shogo-ai/sdk/email/server)
Prisma adapters — PG / SQLite / libSQL auto-detection	@shogo-ai/db (also as @shogo-ai/sdk/db)
Agent runtime — runAgentLoop, model router, hooks	@shogo-ai/agent (also as @shogo-ai/sdk/agent-loop etc.)
TypeScript	Full type safety with generics
Cross-Platform	Browsers, Node, Bun, React Native

The right column tells you where the implementation lives in v1.6+; either path works at the import site.

API Reference

Client Setup

import { createClient } from '@shogo-ai/sdk'

const client = createClient({
  apiUrl: 'http://localhost:3000',  // Your app backend URL
  auth: {
    mode: 'headless',                // 'managed' or 'headless'
    authPath: '/api/auth',           // Auth endpoint path (default)
  },
})

Authentication

// Sign up
const user = await client.auth.signUp({
  email: 'user@example.com',
  password: 'secret',
  name: 'Jane Doe',  // optional
})

// Sign in
const user = await client.auth.signIn({
  email: 'user@example.com',
  password: 'secret',
})

// Get current user (sync)
const user = client.auth.currentUser()

// Get session (async)
const session = await client.auth.getSession()

// Sign out
await client.auth.signOut()

// Listen to auth state changes
const unsubscribe = client.auth.onAuthStateChanged((state) => {
  console.log('Auth state:', state.isAuthenticated, state.user)
})

Database Operations

// List with filtering
const todos = await client.db.todos.list({
  where: { status: 'active' },
  orderBy: { createdAt: 'desc' },
  take: 20,
  skip: 0,
})

// List with query parameters (sent as URL query params)
// Example: GET /api/v2/projects?workspaceId=abc123&status=active
const projects = await client.db.projects.list({
  where: { workspaceId: 'abc123', status: 'active' },
  limit: 20,
})

// You can also use the params option for additional query parameters
const filtered = await client.db.items.list({
  where: { category: 'electronics' },
  params: { sortBy: 'price', order: 'asc' },
})

// Get by ID
const todo = await client.db.todos.get('todo-123')

// Create
const newTodo = await client.db.todos.create({
  title: 'Buy milk',
  completed: false,
})

// Update
await client.db.todos.update('todo-123', {
  completed: true,
})

// Delete
await client.db.todos.delete('todo-123')

// Count
const count = await client.db.todos.count({
  where: { completed: true },
})

Query Operators

// Comparison operators
{ priority: { $gt: 5 } }     // Greater than
{ priority: { $gte: 5 } }    // Greater than or equal
{ priority: { $lt: 5 } }     // Less than
{ priority: { $lte: 5 } }    // Less than or equal
{ status: { $eq: 'active' } } // Equal
{ status: { $ne: 'done' } }   // Not equal

// Array operators
{ tags: { $in: ['urgent', 'important'] } }    // In array
{ tags: { $nin: ['archived'] } }              // Not in array

// Logical operators
{
  $and: [
    { status: 'active' },
    { priority: { $gte: 5 } },
  ]
}

{
  $or: [
    { priority: 10 },
    { status: 'urgent' },
  ]
}

React Integration…