@stacklive/sdk

Build portable, identity-aware app experiences on any website

StackLive SDK enables creators and developers to attach mini-apps to any website using a universal runtime and embed system.

🎯 Platform Support

Works everywhere: Web • React Native • Expo • Node.js

• ✅ Dual builds: ESM + CommonJS for maximum compatibility
• ✅ Zero config: Works out-of-the-box in React Native and Expo (v0.1.5+)
• ✅ No Node.js deps: Removed node-forge for native compatibility
• ✅ Modern & Legacy: Supports both modern ESM and classic CommonJS

🚀 Quick Start

Quick Links:

• ❓ Just need to list apps? See FAQ.md for the direct answer!
• 📖 New to the SDK? Start with QUICKSTART.md for the simplest approach!
• 🔑 Developer account & API keys? See DEVELOPER_SETUP.md for the full guide!

Installation

npm install @stacklive/sdk
# or
pnpm add @stacklive/sdk
# or
yarn add @stacklive/sdk

Simplest Example: List Mini-Apps

You only need 2 imports and 3 lines of code - no manual runtime setup required!

import { flow, list, runFlow } from '@stacklive/sdk';

// 1. Build the flow
const ast = flow('miniapps-list')
  .step(list('miniapps', { id: 'list-apps' }))
  .build();

// 2. Execute it (runtime is auto-created with all capabilities pre-registered)
const result = await runFlow(ast);

// 3. Get results
const apps = result.execution.results['list-apps'].output.apps;

That's it! The SDK automatically:

• ✅ Creates a shared runtime singleton
• ✅ Registers all 90+ platform capabilities
• ✅ Compiles your flow (L8 → L6)
• ✅ Executes via the L7 Kernel

Developer Registration

💡 Is an account required?
No — you can use the full SDK locally without registering. A developer account is only needed when you want to publish apps, track usage/analytics, or use live platform APIs.

See DEVELOPER_SETUP.md for the complete guide including API key types, what tracking is enabled per developer, and how to manage multiple apps.

Guided CLI Setup (recommended)

Run the interactive wizard to register, create your first app, and get API keys in one step:

npx @stacklive/sdk register

This will:

• Register your developer account (or return your existing one)
• Create your first app
• Generate test and live API keys
• Write a .env.local file with all credentials

Alternatively, register in the browser

Visit https://www.stacklive.dev/developer to complete the same steps online.

Create Full Mini-Apps

For more complex apps with agents and workflows:

npx @stacklive/sdk create-app my-app
cd my-app

Example app definition:

import { defineApp, agent } from '@stacklive/sdk';

export const walletApp = defineApp({
  id: 'wallet-onboarding',
  version: '1.0.0',
  capabilities: ['wallet.addPass'],

  agents: (agent) => [
    agent('wallet-agent')
      .capabilities(['wallet.addPass'])
      .onStart(async (ctx) => {
        console.log('Wallet onboarding started');
      })
      .onComplete(async () => {
        console.log('Card added to wallet!');
      })
  ]
});

📚 Core Concepts

Mini-Apps

Portable applications that run on any website through the StackLive runtime. Mini-apps are:

• Declarative: Defined with a simple configuration API
• Portable: Run across different websites and platforms
• Identity-aware: Connected to user identity and data
• Composable: Built from reusable capabilities and agents

Agents

Autonomous entities that handle specific workflows within a mini-app:

import { agent } from '@stacklive/sdk';

const myAgent = agent('onboarding-agent')
  .capabilities(['identity.verify', 'wallet.addPass'])
  .onStart(async (ctx) => {
    // Initialize agent state
  })
  .onResume(async (ctx) => {
    // Resume from pause
  })
  .onComplete(async (ctx) => {
    // Clean up and finish
  })
  .build();

Capabilities

Strongly-typed interfaces to device and platform features:

import { defineCapability } from '@stacklive/sdk';

export const verifyIdentity = defineCapability({
  id: 'identity.verify',
  input: {} as { userId: string },
  output: {} as { verified: boolean },
  handler: async (input) => {
    // Implement verification logic
    return { verified: true };
  }
});

Flows & DSL

Declarative workflows built with the Intent DSL:

import { flow, op, runFlow } from '@stacklive/sdk';

const AUTH_FLOW = flow('auth')
  .step(op('auth.login'))
  .step(op('identity.verify'))
  .step(op('session.create'))
  .build();

// Execute with auto-initialized runtime
const result = await runFlow(AUTH_FLOW);

Key DSL Verbs:

• list(resource) - Fetch collections (e.g., list('miniapps'))
• get(resource) - Fetch single resource
• op(capability) - Execute custom operations
• submit(resource) - Submit data
• request(capability) - Request capability execution
• update(resource) - Update resource
• add(), remove(), del() - Collection operations

When Do You Need Manual Runtime Setup?

You DON'T need manual runtime setup for normal usage! The runFlow() helper handles everything automatically.

Use runFlow() for 99% of cases:

import { flow, list, runFlow } from '@stacklive/sdk';

// ✅ Simple and automatic
const result = await runFlow(
  flow('miniapps-list')
    .step(list('miniapps', { id: 'list-apps' }))
    .build()
);

Only use manual setup for:

1. Custom Capabilities

import { getRuntime } from '@stacklive/sdk';

const runtime = getRuntime();
runtime.registerCapability('custom.action', async (input) => {
  return { success: true };
});

// Now use runFlow() normally - it uses the same shared runtime
const result = await runFlow(myFlow);

2. Testing with Mocks

import { createTestRuntime } from '@stacklive/sdk/test';

const testRuntime = createTestRuntime();
testRuntime.registerCapability('miniapps.list', async () => ({
  apps: [{ id: '1', name: 'Test App' }]
}));

3. Selective Capability Registration (rarely needed)

import { 
  createFlowRuntime, 
  registerMiniAppsCapabilities,
  compile 
} from '@stacklive/sdk';

const runtime = createFlowRuntime();
registerMiniAppsCapabilities(runtime);

const compiled = compile(flowAST);
const result = await runtime.execute(compiled);

💡 Tip: Tree-shaking automatically removes unused capabilities, so selective registration is rarely needed for bundle size optimization.

🛠️ Features

✅ Declarative App Definition

Define complete mini-apps with a simple, declarative API:

import { defineApp } from '@stacklive/sdk';

export const myApp = defineApp({
  id: 'my-app',
  version: '1.0.0',
  capabilities: ['capability.id'],
  agents: (agent) => [/* ... */],
  workflows: (flow) => [/* ... */]
});

✅ 90+ Pre-registered Capabilities

Access built-in capabilities out of the box (automatically registered when using runFlow()):

• Identity & Auth: auth.login, auth.authenticate, session.create
• Wallet & Cards: wallet.addPass, card.provision, payment.process
• AI & Memory: ai.chat, ai.generate, memory.store, memory.recall
• Forms & Receipts: forms.submit, receipt.scan
• Brand & Context: brand.apply, context.get
• Messaging: chatbot.respond, magiclink.send, otp.verify
• Events & Analytics: events.track, analytics.query, analytics.dashboard
• Users: users.create, users.get, users.update, users.delete
• Mini-Apps: miniapps.list, miniapps.favorite, miniapps.unfavorite
• P2P & Contacts: p2p.send, p2p.request, contacts.get
• Fitness: fitness.track, fitness.query
• QR Codes: qr.generate, qr.scan
• WiFi: wifi.share
• Unit Conversion: units.convert
• And 40+ more...

All capabilities are automatically available when using runFlow() - no manual registration needed!

✅ Local Development Runtime

Test and debug locally without infrastructure:

import { createSimulationRuntime } from '@stacklive/sdk';

const runtime = createSimulationRuntime();
await runtime.install(myApp);

const runId = await runtime.start('my-app', { userId: 'test' });
console.log('App started:', runId);

✅ Flow-Based DSL

Build complex workflows with the Intent DSL:

import { flow, op } from '@stacklive/sdk';

const ONBOARDING_FLOW = flow()
  .step(op('identity.verify'))
  .step(op('wallet.addPass'))
  .step(op('session.create'))
  .build();

✅ CLI Tools

The SDK includes powerful CLI tools for the complete developer workflow:

Developer Registration

Register for a StackLive developer account:

npx @stacklive/sdk register

Creates your developer account, first app, and generates API keys automatically.

Create New Apps

Create additional apps and get new API keys:

npx @stacklive/sdk new-app <app-name>
# or
stacklive-new-app wallet-onboarding

Generate App Scaffolds

Generate new app scaffolds instantly:

npx @stacklive/sdk create-app my-app
# or
stacklive create-app my-app

Generates:

my-app/
├── app.ts                    # Main app definition
├── agents/
│   └── my-app-agent.ts       # Agent implementations
├── capabilities/
│   └── my-capability.ts      # Custom capabilities
├── workflows/
│   └── index.ts              # Workflow definitions
├── tests/
│   └── my-app.test.ts        # Integration tests
└── stacklive.config.ts       # App configuration

📚 Documentation

• DEVELOPER_SETUP.md - When an account is required, guided npx registration, API key types & tracking
• FAQ.md - Direct answer: What's needed to list mini-apps? (DSL only!)
• QUICKSTART.md - Quick guide to listing apps and executing flows
• EXAMPLES.md - Complete working examples with code patterns
• API Reference - See below for detailed API documentation

📖 API Reference

Core Exports

// App Definition
import {
  defineApp,
  defineCapability,
  agent,
  AgentBuilder
} from '@stacklive/sdk';

// Flow DSL
import {
  flow,
  op,
  FlowBuilder
} from '@stacklive/sdk';

// Runtime
import {
  createSimulationRuntime,
  createFlowRuntime
} from '@stacklive/sdk';

// Capability Registration
import {
  registerAuthCapabilities,
  registerCardCapabilities,
  registerAiCapabilities,
  // ... and 20+ more
} from '@stacklive/sdk';

Test Utilities

import { createTestRuntime } from '@stacklive/sdk/test';

const runtime = createTestRuntime();
// ... test your app

🏗️ Architecture

StackLive uses a layered architecture (L0-L8):

L8 — Creator (SDK)         ← You are here
  ↓
L7 — Kernel (Execution)    ← Interprets and executes flows
  ↓
L6 — Compute               ← Pure deterministic logic
  ↓
L5 — Variants              ← Declarative definitions
  ↓
L4 — Contracts             ← Type definitions & schemas
  ↓
L3 — Capabilities          ← Device/platform adapters
  ↓
L2 — Runtime               ← Host environment bridge
  ↓
L1 — Transport             ← Communication layer
  ↓
L0 — Environment           ← Browser/Native platform

Key Principles:

1. Only L7 (Kernel) executes - Everything else describes, decides, or connects
2. Downward-only imports - No upward or cross-layer dependencies
3. Determinism at L6 - Pure, replayable computation
4. Capability isolation at L3 - No orchestration, just adapters

📦 Package Structure

This SDK is a wrapper around @stacklive/app-sdk that provides:

• Clean, publishable npm package
• Simplified imports and exports
• Comprehensive documentation
• CLI tooling

Internal Dependencies:

• @stacklive/app-sdk - Core SDK implementation (L8)
• @stacklive/contracts - Type definitions (L4)
• @stacklive/capability - Capability registry (L3)
• @stacklive/runtime-kernel-core - Execution kernel (L7)

🧪 Testing

Run your app tests with the test runtime:

import { createTestRuntime } from '@stacklive/sdk/test';
import { myApp } from './app';

async function runTests() {
  const runtime = createTestRuntime();
  await runtime.install(myApp);

  const runId = await runtime.start('my-app');
  await runtime.emit('my-app.started');

  const state = runtime.getRunState(runId);
  console.assert(state.status === 'completed');
}

runTests();

📝 Examples

Authentication Flow

import { defineApp, flow, op } from '@stacklive/sdk';

export const authApp = defineApp({
  id: 'auth',
  version: '1.0.0',
  capabilities: ['auth.login', 'identity.verify', 'session.create'],

  agents: (agent) => [
    agent('auth-agent')
      .capabilities(['auth.login', 'identity.verify'])
      .onComplete(async () => {
        console.log('Authentication complete');
      })
  ]
});

export const AUTH_FLOW = flow()
  .step(op('auth.login'))
  .step(op('identity.verify'))
  .step(op('session.create'))
  .build();

Wallet Integration

import { defineApp, agent } from '@stacklive/sdk';

export const walletApp = defineApp({
  id: 'wallet',
  version: '1.0.0',
  capabilities: ['wallet.addPass', 'card.provision'],

  agents: (agent) => [
    agent('wallet-agent')
      .capabilities(['wallet.addPass'])
      .entry('wallet.addPass', {
        type: 'loyalty',
        cardData: { /* ... */ }
      })
      .onComplete(async () => {
        console.log('Card added to wallet');
      })
  ]
});

AI Chat Assistant

import { defineApp, flow, op } from '@stacklive/sdk';

export const chatApp = defineApp({
  id: 'ai-chat',
  version: '1.0.0',
  capabilities: ['ai.chat', 'memory.store', 'memory.recall'],

  agents: (agent) => [
    agent('chat-agent')
      .capabilities(['ai.chat', 'memory.store'])
      .onStart(async (ctx) => {
        const history = await ctx.invoke('memory.recall', {
          key: 'chat-history'
        });
        ctx.metadata.history = history;
      })
  ]
});

export const CHAT_FLOW = flow()
  .step(op('memory.recall'))
  .step(op('ai.chat'))
  .step(op('memory.store'))
  .build();

🔧 Configuration

Environment Variables

After registering, you'll have a .env.local file with your credentials:

# Developer Credentials
STACKLIVE_API_KEY=pk_test_your_test_key_here
STACKLIVE_DEVELOPER_ID=your_developer_id

# Platform Configuration
STACKLIVE_API_URL=https://api.stacklive.dev

# App Configuration
APP_ID=your_app_id
APP_VERSION=1.0.0
NODE_ENV=development

For additional configuration options (Convex, OpenAI, Supabase, Stripe, etc.), see the included .env.local.sample file.

App Configuration

Create a stacklive.config.ts in your project:

export default {
  appId: 'my-app',
  version: '1.0.0',

  distribution: {
    entry: './dist/app.js',
    registry: 'https://registry.stacklive.dev/apps'
  },

  dev: {
    port: 3100,
    hmr: true
  }
};

🤝 Contributing

This SDK is part of the StackLive monorepo. Contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

MIT © StackLive

🔗 Resources

• GitHub: https://github.com/rkendel1/temp_live
• Documentation: Coming soon
• Examples: See apps/sample-mini-app in the monorepo
• Issues: https://github.com/rkendel1/temp_live/issues

💡 Philosophy

StackLive turns a system you built into a system others can build on.

The SDK enables:

• Creators to build portable experiences
• Developers to extend the platform
• Users to own their identity and data across the web

Built with ❤️ by the StackLive team.