npm package: @sensei-ecosystem/sdk
Description: Official TypeScript SDK for the SenseiTemple platform. White-label ready, AI agent compatible.
Author: SenseiTemple
Latest version: 0.1.0

# SenseiTemple SDK

The official TypeScript/JavaScript SDK for the SenseiTemple platform. Build white-label personal development, coaching, and community applications with full AI agent compatibility.

## Highlights

- **White-Label Ready** - Every feature is embeddable without SenseiTemple branding. Custom domains, themes, colors, and feature toggles.
- **Agent-Compatible** - Built for AI agents (Claude, Codex, GPT). Authenticate with API keys, get typed tool definitions, and chain operations programmatically.
- **Full Type Safety** - Complete TypeScript definitions for all 60+ business domains, 593 models, and 2000+ API endpoints.
- **12 Modules** - Clean abstraction over the entire platform: auth, users, guilds, services, bookings, messaging, payments, gamification, content, AI, realtime, and admin.
- **MCP Server** - Ships with a Model Context Protocol server for seamless integration with Claude Desktop and Claude Code.

---

## Installation

```bash
npm install @senseitemple/sdk
```

For the MCP server (Claude Desktop / Claude Code integration):

```bash
npm install -g @senseitemple/mcp-server
```

---

## Quick Start

### API Key Authentication (AI Agents & Partners)

```typescript
import { SenseiTemple } from '@senseitemple/sdk'

const client = new SenseiTemple({
  apiKey: 'st_key_xxx',
  apiSecret: 'st_secret_xxx',
  baseUrl: 'https://api.senseitemple.com',
})

// Create a guild
const guild = await client.guilds.create({
  name: 'Growth Hackers',
  description: 'A community for continuous improvement',
  visibility: 'public',
})

// Start a kaizen group inside the guild
const kaizen = await client.gamification.kaizen.create(guild.id, {
  name: '30-Day Morning Routine',
  frequency: 'daily',
  stakAmount: 50,
})
```

### Bearer Token (Server-to-Server)

```typescript
const client = new SenseiTemple({
  token: 'your_sanctum_token',
  baseUrl: 'https://api.senseitemple.com',
})
```

### Session Auth (Browser SPA / White-Label)

```typescript
const client = new SenseiTemple({
  baseUrl: 'https://app.yourbrand.com',
  withCredentials: true,
})
```

---

## Modules

### `auth` - Authentication & OAuth

```typescript
// Register a new user
const user = await client.auth.register({
  name: 'John Doe',
  email: 'john@example.com',
  password: 'securepassword',
})

// Login
const session = await client.auth.login({
  email: 'john@example.com',
  password: 'securepassword',
})

// OAuth (Google, Apple, Discord, Spotify, TikTok, LinkedIn)
const oauthUrl = await client.auth.getOAuthUrl('google', {
  redirectUri: 'https://app.yourbrand.com/callback',
})
```

### `users` - Profiles & Social

```typescript
// Get user profile
const profile = await client.users.get('username')

// Update profile
await client.users.update({ bio: 'Building the future', skills: ['coaching', 'leadership'] })

// Follow / unfollow
await client.users.follow(userId)
await client.users.unfollow(userId)

// Trust score
const trust = await client.users.trustScore(userId)

// Monthly wrapped recap
const wrapped = await client.users.wrapped.get('2026-03')
```

### `guilds` - Communities & Organizations

```typescript
// List guilds
const guilds = await client.guilds.list({ page: 1, perPage: 20 })

// Guild members management
const members = await client.guilds.members.list(guildId)
await client.guilds.members.add(guildId, userId, { role: 'member' })
await client.guilds.members.updateRole(guildId, memberId, 'manager')

// Guild roles & permissions (50+ permission types)
const roles = await client.guilds.roles.list(guildId)
await client.guilds.roles.create(guildId, {
  name: 'Moderator',
  permissions: ['manage_members', 'moderate_chat', 'manage_events'],
})

// Arena challenges
await client.guilds.arena.create(guildId, {
  name: 'Weekly Sprint',
  type: 'competition',
  duration: '7d',
})

// Governance
await client.guilds.governance.createVote(guildId, {
  title: 'New community rules',
  options: ['Approve', 'Reject'],
  duration: '48h',
})
```

### `services` - Marketplace & Catalogue

```typescript
// Create a coaching service
const service = await client.services.create({
  name: 'Leadership Coaching',
  type: 'coaching',
  pricing: [
    { tier: 'basic', price: 99, currency: 'EUR', benefits: ['1h session'] },
    { tier: 'premium', price: 249, currency: 'EUR', benefits: ['3h session', 'follow-up'] },
  ],
  locations: { online: true, platforms: ['zoom', 'google_meet'] },
})

// Browse marketplace
const results = await client.services.marketplace.search({
  query: 'coaching leadership',
  category: 'professional',
  priceRange: { min: 50, max: 300 },
})

// Coupons
await client.services.coupons.create(serviceId, {
  code: 'LAUNCH20',
  discount: 20,
  type: 'percentage',
})
```

### `bookings` - Scheduling & Calendar

```typescript
// Get available slots
const slots = await client.bookings.availability(serviceId, {
  date: '2026-04-15',
  timezone: 'Europe/Paris',
})

// Book a service
const booking = await client.bookings.create({
  serviceId,
  pricingTierId,
  slot: '2026-04-15T10:00:00+02:00',
})

// Sync with Google Calendar
await client.bookings.calendar.syncGoogle({ calendarId: 'primary' })
```

### `messaging` - E2E Encrypted Chat

```typescript
// List conversations
const conversations = await client.messaging.conversations.list()

// Send a message (E2E encrypted with AES-256-GCM)
await client.messaging.messages.send(conversationId, {
  content: 'Hello! Ready for our session?',
})

// Create a poll
await client.messaging.polls.create(conversationId, {
  question: 'Best time for next meeting?',
  options: ['Monday 10am', 'Tuesday 2pm', 'Wednesday 4pm'],
})

// React to a message
await client.messaging.messages.react(messageId, '🔥')
```

### `payments` - Stripe Integration

```typescript
// Create a subscription
const subscription = await client.payments.subscriptions.create({
  planId: 'pro_monthly',
  paymentMethodId: 'pm_xxx',
})

// Stripe Connect (multi-vendor)
const connectAccount = await client.payments.connect.setup({
  type: 'express',
  country: 'FR',
})

// Payouts
const payouts = await client.payments.payouts.list({ status: 'pending' })

// Invoices
const invoices = await client.payments.invoices.list()

// Tips
await client.payments.tips.send(userId, { amount: 5, currency: 'EUR' })
```

### `gamification` - Quests, Kaizen, Badges & More

```typescript
// Quest system
const quests = await client.gamification.quests.list()
await client.gamification.quests.start(questId)
await client.gamification.quests.submitProof(questId, {
  type: 'image',
  url: 'https://...',
  description: 'Completed my morning routine',
})

// Kaizen habit groups
const group = await client.gamification.kaizen.create({
  name: '21-Day Meditation',
  frequency: 'daily',
  stakAmount: 30,
})
await client.gamification.kaizen.submitMission(groupId, {
  proof: { type: 'photo', url: '...' },
})

// XP, levels, streaks
const stats = await client.gamification.stats()
// { xp: 2450, level: 12, streak: 7, badges: [...] }

// Ikigai (life purpose + AI vision board)
const ikigai = await client.gamification.ikigai.generate({
  passions: ['teaching', 'technology'],
  skills: ['public speaking', 'coding'],
  needs: ['education', 'mentorship'],
})

// Vision boards
await client.gamification.visionMix.create({
  goals: ['Learn Spanish', 'Run a marathon'],
  habits: ['30min study daily', 'Run 3x/week'],
})
```

### `content` - Courses, Events & Publications

```typescript
// Create a course
const course = await client.content.courses.create({
  title: 'Mastering Public Speaking',
  modules: [
    {
      title: 'Foundations',
      lessons: [
        { title: 'Finding Your Voice', type: 'video', duration: '15min' },
        { title: 'Body Language', type: 'video', duration: '20min' },
      ],
    },
  ],
  quiz: { questions: [...] },
  certificate: true,
})

// Events
const event = await client.content.events.create({
  title: 'Community Meetup',
  date: '2026-05-01T18:00:00+02:00',
  location: { type: 'hybrid', address: '...', onlineUrl: '...' },
  speakers: [{ userId, topic: 'Growth Mindset' }],
})

// RSVP
await client.content.events.attend(eventId)

// Forums (Blue Phoenix)
await client.content.forums.createTopic({
  title: 'Best practices for habit tracking',
  category: 'personal-development',
  content: '...',
})

// Email campaigns (Mailjet)
await client.content.campaigns.create({
  name: 'Welcome Series',
  template: 'welcome_v2',
  audience: { segment: 'new_users_7d' },
  schedule: '2026-04-10T09:00:00Z',
})
```

### `ai` - Anubis, Image/Video Generation & Recommendations

```typescript
// Chat with Anubis AI
const response = await client.ai.chat({
  message: 'What quests should I focus on this week?',
})

// Generate an image (fal.ai - FLUX, Kontext, PuLID models)
const image = await client.ai.generateImage({
  prompt: 'A serene mountain landscape at sunrise',
  model: 'flux-schnell', // or 'flux-pro', 'kontext-pro', 'kontext-max', 'pulid-flux'
  size: 'landscape_16_9',
})

// Generate a video (MiniMax, Kling models)
const video = await client.ai.generateVideo({
  prompt: 'Calm ocean waves on a tropical beach',
  model: 'kling-2.5-turbo',
  duration: '5s',
})

// Get recommendations
const recommendations = await client.ai.recommendations({
  type: 'services',
  limit: 10,
})

// Intent signals & warm leads
const warmLeads = await client.ai.warmLeads.list()
```

### `realtime` - WebSocket & Video Conferencing

```typescript
// Subscribe to real-time events
client.realtime.connect()

client.realtime.on('message', (event) => {
  console.log('New message:', event.data)
})

client.realtime.on('notification', (event) => {
  console.log('Notification:', event.data)
})

// Presence tracking
client.realtime.presence.join(channelId)
client.realtime.presence.onUpdate((users) => {
  console.log('Online users:', users)
})

// Video conferencing (LiveKit)
const room = await client.realtime.video.createRoom({
  name: 'coaching-session',
  maxParticipants: 2,
})
const token = await client.realtime.video.getToken(room.id)
```

### `admin` - Administration & Compliance

```typescript
// User management
const users = await client.admin.users.list({ search: 'john', page: 1 })
await client.admin.users.ban(userId, { reason: 'TOS violation', duration: '30d' })

// GDPR
await client.admin.gdpr.exportData(userId)
await client.admin.gdpr.deleteData(userId)

// Feature flags
await client.admin.featureFlags.toggle('new_onboarding', true)

// Analytics
const kpis = await client.admin.analytics.dashboard({
  period: 'last_30d',
  metrics: ['revenue', 'active_users', 'new_guilds'],
})

// Moderation
const reports = await client.admin.moderation.reports.list({ status: 'pending' })
```

---

## White-Label Configuration

Customize every aspect of the platform for your brand:

```typescript
const client = new SenseiTemple({
  apiKey: 'st_key_xxx',
  apiSecret: 'st_secret_xxx',
  whiteLabel: {
    appName: 'MyBrand Academy',
    logo: 'https://mybrand.com/logo.png',
    favicon: 'https://mybrand.com/favicon.ico',
    colors: {
      primary: '#FF6B00',
      secondary: '#1A1A2E',
      accent: '#E94560',
    },
    fonts: {
      heading: 'Inter',
      body: 'system-ui',
    },
    domain: 'app.mybrand.com',
    locale: 'fr',
    features: {
      guilds: true,
      kaizen: true,
      messaging: true,
      quests: true,
      courses: true,
      marketplace: false,      // Disable features you don't need
      videoConference: false,
      blockchain: false,
      lottery: false,
    },
  },
})
```

---

## AI Agent Integration

### Tool Definitions

Generate tool definitions compatible with OpenAI, Anthropic, and other AI agent frameworks:

```typescript
// Get all available tools
const tools = client.agent.getTools()

// Filter by module
const messagingTools = client.agent.getTools({ modules: ['messaging', 'guilds'] })

// Filter by operation type
const readOnlyTools = client.agent.getTools({ methods: ['list', 'get'] })

// Execute a tool call from an AI agent
const result = await client.agent.execute({
  name: 'senseitemple_guilds_create',
  arguments: {
    name: 'AI Study Group',
    description: 'Learning AI together',
    visibility: 'public',
  },
})
```

### MCP Server (Claude Desktop / Claude Code)

Configure the MCP server for direct Claude integration:

```json
// ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "senseitemple": {
      "command": "senseitemple-mcp",
      "env": {
        "SENSEITEMPLE_API_KEY": "st_key_xxx",
        "SENSEITEMPLE_API_SECRET": "st_secret_xxx",
        "SENSEITEMPLE_BASE_URL": "https://api.senseitemple.com"
      }
    }
  }
}
```

Then in Claude, you can simply say:

> "Create a guild called 'Morning Warriors', add 3 members, and start a 30-day kaizen challenge for meditation."

Claude will chain the SDK operations automatically.

### Supported AI Agents

| Agent | Integration Method |
|---|---|
| Claude (Anthropic) | MCP Server, Tool Use API |
| Claude Code | MCP Server |
| GPT (OpenAI) | Function Calling |
| Codex | Function Calling |
| Custom Agents | Tool definitions export |

---

## SDK Modules Overview

| Module | Description | Key Features |
|---|---|---|
| `auth` | Authentication & OAuth | Register, login, 6 OAuth providers, sessions |
| `users` | Profiles & Social | 63+ profile attributes, follow, trust scores, wrapped recaps |
| `guilds` | Communities | RBAC (50+ permissions), compensation, arena, governance |
| `services` | Marketplace | Coaching services, multi-tier pricing, coupons, catalogue |
| `bookings` | Scheduling | Calendar, availability, Google Calendar sync |
| `messaging` | Encrypted Chat | E2E encryption (AES-256-GCM), polls, reactions |
| `payments` | Stripe | Subscriptions, Connect (multi-vendor), invoices, payouts |
| `gamification` | Quests & Habits | Quests, kaizen, XP/levels, badges, ikigai, vision boards |
| `content` | Learning & Events | Courses, events, forums, email campaigns |
| `ai` | AI Features | Chatbot, image/video generation (fal.ai), recommendations |
| `realtime` | WebSocket & Video | Real-time events, presence, LiveKit video conferencing |
| `admin` | Administration | User mgmt, GDPR, moderation, feature flags, analytics |

---

## Backend Domains Covered

The SDK wraps **60+ business domains** from the SenseiTemple platform:

Auth, Account, Actor, Profile, Guild, Squad, Alliance, Raid, Arena, Tournament, Governance, Service, Marketplace, Catalogue, Booking, BookingProfile, Availability, GoogleCalendar, Messaging, Chat, Announcement, Payment, Subscription, Checkout, Remuneration, Vesting, Monetization, TipTop, Quest, Kaizen, Badge, VisionMix, Ikigai, TruthCards, Streak, Protocol, Course, BluePhoenix, Publication, Questionnaire, Event, Campaign, Emailing, Anubis, Media, Recommendation, LiveMatch, VideoConference, Broadcasting, Notification, Admin, GDPR, Moderation, Security, FeatureFlags, Analytics, Ambassador, Cosmetic, Wrapped, Follow, TrustScore, Slug, Coupon, Lottery, Auction, and more.

---

## Error Handling

```typescript
import { SenseiTempleError, ValidationError, AuthError } from '@senseitemple/sdk'

try {
  await client.guilds.create({ name: '' })
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.errors) // { name: ['The name field is required.'] }
  }
  if (error instanceof AuthError) {
    console.log('Authentication failed:', error.message)
  }
}
```

---

## Requirements

- **Node.js** 18+ or modern browser
- **TypeScript** 5+ (optional but recommended)
- SenseiTemple API credentials (API key or Sanctum token)

---

## Contributing

We welcome contributions. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## Links

- [SenseiTemple Platform](https://senseitemple.com)
- [API Documentation](https://docs.senseitemple.com)
- [MCP Server](https://www.npmjs.com/package/@senseitemple/mcp-server)
- [Discord Community](https://discord.gg/senseitemple)