Skip to Content

isA App SDK

TypeScript SDK packages for the isA ecosystem across web, React Native, and device-facing clients.

Packages

PackagePurpose
@isa/coreService clients, shared types, IsAClient, auth, resilience
@isa/transportHTTP, MQTT, WebSocket, and SSE transport helpers
@isa/hooksReact hooks built on top of @isa/core
@isa/themeDesign tokens and theme objects
@isa/ui-webReact web components
@isa/ui-nativeReact Native components
@isa/service-agentsEmbeddable vertical service-agent widgets and gateway clients

Latest Updates (2026-05-17)

  • @isa/service-agents adds an embeddable web widget for service-agent chat surfaces.
  • The gateway exposes agent discovery and channel-aware chat routes under /api/v1/service-agents.
  • The widget bundle mounts from window.IsAServiceAgents and uses Shadow DOM isolation for host-page safety.
  • A2UI contracts now include richer controls and layouts: Knob, ColorPicker, RangeSlider2D, DraggableCard, DropZone, ComparisonGrid, AnnotatedDiff, and FlowDiagram.

Install

The @isa scope is currently configured for GitHub Packages.

pnpm add @isa/core

If you are installing from GitHub Packages, configure your npm registry for the @isa scope before install.

Quick Start

@isa/core

import { IsAClient } from '@isa/core'
 
const client = new IsAClient({
  baseUrl: 'http://localhost:80',
  resilience: { enabled: false },
})
 
const login = await client.auth.login('user@example.com', 'password123')
 
if (login.success) {
  const products = await client.product.getProducts()
  const devices = await client.device.listDevices({ limit: 10 })
  console.log(products, devices)
}

@isa/transport

import { HttpClient } from '@isa/transport'
 
const http = new HttpClient({
  baseURL: 'http://localhost:80',
  headers: {
    Authorization: 'Bearer token',
  },
})
 
const products = await http.get('/api/v1/product/products')
console.log(products)

@isa/hooks

useAuth expects an AuthService instance.

import { AuthService } from '@isa/core'
import { useAuth } from '@isa/hooks'
 
const authService = new AuthService({ baseUrl: 'http://localhost:80' })
 
function AuthPanel() {
  const { isAuthenticated, user, login, logout, isLoading, error } = useAuth({
    authService,
  })
 
  return (
    <div>
      {isAuthenticated ? (
        <>
          <p>Signed in as {user?.email}</p>
          <button onClick={logout}>Logout</button>
        </>
      ) : (
        <button onClick={() => login('user@example.com', 'password123')}>
          Login
        </button>
      )}
      {isLoading && <p>Loading...</p>}
      {error && <p>{error}</p>}
    </div>
  )
}

@isa/ui-web

import { ChatInput, MarkdownRenderer } from '@isa/ui-web'
 
function ChatExample() {
  return (
    <div>
      <MarkdownRenderer content="**Hello from isA**" />
      <ChatInput onSend={(value) => console.log(value)} />
    </div>
  )
}

@isa/theme

@isa/theme exports tokens and theme objects rather than a framework-specific provider.

import { colors, spacing, typography, lightTheme } from '@isa/theme'
 
console.log(colors.primary[500], spacing[4], typography.fontSizes.base, lightTheme)

@isa/service-agents

<script src="/service-agents-widget.js"></script>
<script>
  window.IsAServiceAgents.mount({
    endpoint: "http://localhost:3000",
    defaultAgentId: "sleep-advisor",
    title: "Ask our team"
  })
</script>

Gateway routes:

MethodRoutePurpose
GET/healthzWidget gateway health
GET/api/v1/service-agentsList available service agents
POST/api/v1/service-agents/:agentId/chatSend a chat message
POST/api/v1/service-agents/:agentId/chat/:channelSend a channel-specific chat message

Local Development

git clone https://github.com/xenoISA/isA_App_SDK
cd isA_App_SDK
pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm build

Notes

  • Consumer apps should import @isa/* packages directly and avoid local aliases to SDK dist folders.
  • The root SDK build command validates publishable packages; example apps can be built separately when needed.
  • Release validation currently targets GitHub Packages, matching the package metadata in the SDK repo.
Home