Jarvis Embed SDK¶

Embed the Jarvis AI Assistant in any web application. Works with bundlers and script tags.

Installation¶

npm install @ascending-inc/jarvis-embed

Browser (no bundler)¶

A pre-built UMD bundle is served via GitHub Pages. Load the latest version directly with a <script> tag and access the class via window.JarvisSDK:

<script src="https://ascending-llc.github.io/jarvis-embed/latest/jarvis-embed.js"></script>
<script>
  const { JarvisEmbed } = window.JarvisSDK;

  const jarvis = new JarvisEmbed({
    provider:    'google',
    token:       googleIdToken,
    apiUrl:      'https://jarvis.host.com',
    containerId: 'chat-container',
  });
</script>

To pin to a specific version, replace latest with the version number:

<script src="https://ascending-llc.github.io/jarvis-embed/0.1.3/jarvis-embed.js"></script>

The bundle is also included in the npm package at dist/index.global.js if you prefer to self-host it.

Usage¶

import { JarvisEmbed } from '@ascending-inc/jarvis-embed';

const jarvis = new JarvisEmbed({
  provider:    'google',
  token:       googleIdToken,
  containerId: 'chat-container',
  apiUrl:       'https://jarvis.host.com',
  spec:        'my-spec',
  agentId:     'agent_123',
  artifactsButton: false,
  onReady:     (jarvisToken) => jarvis.setMcpServers(['my-mcp-server']),
});

Options¶

Option	Type	Default	Description
`provider`	`AuthProvider`	Required	Auth provider — see Authentication.
`apiUrl`	`string`	Required	Jarvis API endpoint (e.g. `https://jarvis.host.com`).
`token`	`string`	Required (except `hmac`)	OAuth / JWT token. Omit for `hmac`.
`containerId`	`string`	—	ID of the DOM element to mount the iframe into.
`container`	`HTMLElement`	—	Direct element reference (alternative to `containerId`).
`width`	`string`	`'100%'`	CSS width of the iframe.
`height`	`string`	`'600px'`	CSS height of the iframe.
`iframeUrl`	`string`	`{apiUrl}/v1/chat`	Override just the embedded chat page URL. Useful for local iframe testing while keeping auth/API calls pointed at `apiUrl`.
`spec`	`string`	—	Spec identifier to use for the conversation (sent as `?spec=` to the API). Retrieve available values from `GET {apiUrl}/api/config`.
`agentId`	`string`	—	Agent identifier to use for the conversation (sent as `?agent_id=` to the embedded chat).
`artifactsButton`	`boolean`	`false`	Initial visibility state of the artifacts button in the embedded chat UI.
`debug`	`boolean`	`false`	Log SDK activity to the console.
`onReady`	`(jarvisToken: string) => void`	—	Fires when the iframe is authenticated and ready. Receives the Jarvis session token — use it to call Jarvis APIs (e.g. `GET {apiUrl}/api/mcp/servers`) on behalf of the user.
`onError`	`(err: Error) => void`	—	Fires on failure.
`onMessage`	`(data: unknown) => void`	—	Fires when the iframe posts a message to the host page.

If neither containerId nor container is provided the iframe appends to document.body.

Local iframe testing¶

If you want to use production auth/API endpoints but load the chat UI from a local dev server, set iframeUrl separately:

new JarvisEmbed({
  provider: 'google',
  token: googleIdToken,
  containerId: 'chat-container',
  apiUrl: 'https://jarvis.host.com',
  iframeUrl: 'http://localhost:3090/c/new',
});

When iframeUrl is provided, the SDK will:

keep token exchange and API calls on apiUrl
load the iframe from iframeUrl
use the iframeUrl origin for postMessage

Getting a spec¶

Available specs can be retrieved from the Jarvis config endpoint:

GET {apiUrl}/api/config

Using an agent¶

To start the embedded chat in agent mode, pass agentId in the constructor config:

new JarvisEmbed({
  provider:    'google',
  token:       googleIdToken,
  containerId: 'chat-container',
  apiUrl: 'https://jarvis.host.com',
  agentId:     'agent_123',
});

Authentication¶

For google, s_jwt, a_jwt, and hmac, the SDK sends your auth payload to POST {apiUrl}/api/auth/exchange, and Jarvis returns a short-lived session token for the embedded chat. With direct, the SDK skips the exchange call and uses your JWT as-is.

`google`¶

Pass the Google id_token you receive from OAuth2 directly — no server-side token signing is required.

Provider	Token
`google`	Google `id_token` from OAuth2

`s_jwt` / `a_jwt`¶

Provider	Token
`s_jwt`	JWT signed with a shared secret (HS256)
`a_jwt`	JWT signed with a private key (RS256 / ES256)

Generating the token on your server¶

Your server signs a JWT that Jarvis verifies. The two providers differ only in the signing algorithm and key material:

Provider	Algorithm	Signing key	Jarvis verifies with
`s_jwt`	`HS256`	A shared secret (`CUSTOM_JWT_SECRET`)	The same shared secret
`a_jwt`	`RS256` (or `ES256`)	Your RSA/EC private key (`CUSTOM_JWT_PRIVATE_KEY`)	The matching public key

The iss, aud, and (for a_jwt) kid values must match the configured values in the Jarvis deployment.

Required claims

These are the claims Jarvis validates on every token.

Claim	Type	Description
`sub`	`string`	Username — a user's login ID. Must be a stable, unique identifier (e.g. username@domain.com)
`iss`	`string`	Issuer — the base URL of the Jarvis deployment.
`aud`	`string`	Audience — (e.g. `"jarvis-services"`).
`iat`	`number`	Issued-at Unix timestamp (seconds).
`exp`	`number`	Expiry Unix timestamp (seconds). Maximum 24 hours from `iat`.

JWT header

Field	Value
`alg`	`HS256` for `s_jwt`, `RS256` / `ES256` for `a_jwt`
`kid`	Key ID (`a_jwt` only)

Node.js example

The payload is identical for both providers — only the signing options change. Swap the commented block to switch providers:

import jwt from 'jsonwebtoken';

const JARVIS_ISS = 'https://jarvis.host.com';
const JARVIS_AUD = 'jarvis-services';

function generateJarvisToken(username, { expiresInHours = 1 } = {}) {
  const now = Math.floor(Date.now() / 1000);

  const payload = {
    sub: username,
    iss: JARVIS_ISS,
    aud: JARVIS_AUD,
    iat: now,
    exp: now + expiresInHours * 3600,
  };

  // a_jwt — sign with an RSA/EC private key
  return jwt.sign(payload, process.env.CUSTOM_JWT_PRIVATE_KEY, {
    algorithm: 'RS256',
    keyid: 'self-signed-key-v1',
  });

  // s_jwt — sign with a shared secret
  // return jwt.sign(payload, process.env.CUSTOM_JWT_SECRET, {
  //   algorithm: 'HS256',
  // });
}

Environment variables¶

Your server

Variable	Description
`CUSTOM_JWT_PRIVATE_KEY`	PEM-encoded RSA/EC private key used to sign `a_jwt` tokens.
`CUSTOM_JWT_SECRET`	Shared secret used to sign `s_jwt` tokens.

The iss, aud, and kid values are deployment-specific constants that can be hardcoded or stored as environment variables. They must match exactly what Jarvis is configured to expect.

Jarvis

Variable	Description
`CUSTOM_JWT_PUBLIC_KEY`	PEM-encoded RSA/EC public key. Jarvis uses this to verify `a_jwt` tokens signed by your server.
`CUSTOM_JWT_SECRET`	Shared secret. Jarvis uses this to verify `s_jwt` tokens.
`CUSTOM_JWT_ISSUER`	Expected issuer claim value (e.g., "https://jarvis.host.com").
`CUSTOM_JWT_AUDIENCE`	Expected audience claim value (e.g., "jarvis-services").
`ALLOW_EMBED`	Set to `true` to enable the embed token flow (`/api/auth/exchange` and direct tokens).

`direct`¶

With direct, your server mints the Jarvis-trusted JWT itself and the SDK uses it as-is — the /api/auth/exchange round-trip is skipped.

new JarvisEmbed({
  provider:    'direct',
  token:       jarvisToken, // generated by your server
  apiUrl: 'https://jarvis.host.com',
  containerId: 'chat-container',
});

How the token is authenticated¶

The direct token is delivered to the embedded chat via SDK_AUTH and presented as a Bearer token on every request to Jarvis. Jarvis validates it through its Passport strategies, choosing one per request:

Condition	Strategy
`OPENID_REUSE_TOKENS=true` and the request carries a `token_provider=openid` cookie with a valid signed session	`openidJwt`
Default	`jwt`

The openidJwt strategy loads the federated tokens from the server-side session, which is resolved using the Session ID cookie the browser sends with each request. If that cookie is missing, expired, or the session store has been cleared, req.session cannot be hydrated and Jarvis will fall back to the standard jwt strategy or return a 401 error code.

`hmac`¶

new JarvisEmbed({
  provider:  'hmac',
  userId:    'user_123',
  timestamp: Math.floor(Date.now() / 1000),
  signature: hmacHex, // HMAC-SHA256(userId + timestamp)
  containerId: 'chat-container',
  apiUrl: 'https://jarvis.host.com',
});

Requests older than 5 minutes are rejected server-side.

Methods¶

Method	Signature	Description
`destroy`	`() => void`	Removes the iframe and cleans up the `window` message listener. Call this on unmount — essential for React.
`setMcpServers`	`(servers: string[]) => void`	Activates one or more MCP servers by name. Safe to call before the iframe is ready — servers are queued and flushed automatically on `SDK_READY`.
`setArtifactsButton`	`(enabled: boolean) => void`	Shows or hides the artifacts button at runtime. Safe to call before the iframe is ready — the latest value is queued and applied automatically on `SDK_READY`.
`setAgentId`	`(agentId: string) => void`	Switches the embedded chat to a specific agent at runtime. Safe to call before the iframe is ready — the latest value is queued and applied automatically on `SDK_READY`. Empty or whitespace-only values are ignored.

MCP (Model Context Protocol)¶

Pass one or more MCP server names to give Jarvis access to external tools and data sources during a session.

Discovering available servers¶

Call GET {apiUrl}/api/mcp/servers with the Jarvis token as a Bearer header to retrieve the names of all servers available to the authenticated user. The response is an object keyed by server name:

const jarvis = new JarvisEmbed({
  provider:    'google',
  token:       googleIdToken,
  containerId: 'chat-container',
  apiUrl: 'https://jarvis.host.com',
  onReady: async (jarvisToken) => {
    const res = await fetch(`${apiUrl}/api/mcp/servers`, {
      headers: { Authorization: `Bearer ${jarvisToken}` },
    });
    const servers = await res.json(); // { "posthog": {...}, "github": {...}, ... }
    const names = Object.keys(servers);

    // Activate all of them, or let the user pick from `names`
    jarvis.setMcpServers(names);
  },
});

Activating servers¶

The safest place to call setMcpServers is inside onReady, which fires once the iframe has authenticated and is listening:

const jarvis = new JarvisEmbed({
  provider:    'google',
  token:       googleIdToken,
  containerId: 'chat-container',
  apiUrl: 'https://jarvis.host.com',
  onReady: () => {
    jarvis.setMcpServers(['posthog', 'aws-knowledge']);
  },
});

You can also call it at any time after instantiation — if the iframe isn't ready yet the servers are queued internally and sent as soon as SDK_READY fires:

const jarvis = new JarvisEmbed({
  provider:    's_jwt',
  token:       myJwt,
  containerId: 'chat-container',
  apiUrl: 'https://jarvis.host.com',
});

// Called immediately — queued until SDK_READY
jarvis.setMcpServers(['github', 'jira']);

To swap the active server set later (e.g. after a user action), call setMcpServers again with the new list:

document.getElementById('enable-analytics')?.addEventListener('click', () => {
  jarvis.setMcpServers(['posthog']);
});

`setArtifactsButton(enabled: boolean)`¶

Shows or hides the artifacts button at runtime. If called before the iframe is ready, the value is queued and applied once the SDK is ready.

jarvis.setArtifactsButton(true);
jarvis.setArtifactsButton(false);

`setAgentId(agentId: string)`¶

Switches the embedded chat to a specific agent at runtime. If called before the iframe is ready, the value is queued and applied once the SDK is ready.

jarvis.setAgentId('agent_123');

This is useful when the host app lets the user choose an agent after the widget has already been mounted:

document.getElementById('agent-picker')?.addEventListener('change', (event) => {
  const nextAgentId = (event.target as HTMLSelectElement).value;
  jarvis.setAgentId(nextAgentId);
});

React¶

useJarvis is not exported from the package — copy examples/react/src/useJarvis.ts into your project. It wraps JarvisEmbed in a useEffect and calls destroy() on unmount automatically:

import { useEffect, useRef } from 'react';
import { JarvisEmbed } from '@ascending-inc/jarvis-embed';
import type { JarvisConfig } from '@ascending-inc/jarvis-embed';

export function useJarvis(config: JarvisConfig | null) {
  const jarvisRef = useRef<JarvisEmbed | null>(null);

  useEffect(() => {
    if (!config) return;
    jarvisRef.current = new JarvisEmbed(config);
    return () => {
      jarvisRef.current?.destroy();
      jarvisRef.current = null;
    };
  }, [config]);

  return jarvisRef;
}

Pass null to defer initialization until the user is authenticated. The hook calls destroy() automatically on unmount, so there are no memory leaks or stale event listeners.

Using the `container` prop in React¶

When mounting into a React-managed DOM node, use a callback ref so initialization only happens once the element actually exists. Wrap config in useMemo with the container as a dependency — this ensures the SDK sees a real HTMLElement, not null:

import { useCallback, useMemo, useState } from 'react';
import { useJarvis } from './useJarvis';

function ChatWidget({ googleToken }: { googleToken: string }) {
  const [container, setContainer] = useState<HTMLDivElement | null>(null);

  const config = useMemo(() => {
    if (!container || !googleToken) return null;
    return {
      provider: 'google' as const,
      token:    googleToken,
      container,
      width:    '100%',
      height:   '100%',
      onReady:  (jarvisToken: string) => {
        // fetch available servers and activate them
      },
    };
  }, [container, googleToken]);

  const jarvisRef = useJarvis(config);

  return <div ref={setContainer} style={{ flex: 1 }} />;
}

Using containerId instead avoids this entirely — the SDK does the getElementById lookup itself after the iframe loads — but the container prop approach above is required when the element is managed by React state.

Examples¶

Both examples demonstrate Google OAuth, MCP tool selection, and embedding the chat widget. They share the same Express backend for token exchange.

1. Clone and set up¶

git clone https://github.com/ascending-llc/jarvis-embed.git
cd jarvis-embed
npm run setup

setup installs root dependencies, builds the SDK, and installs dependencies for both examples.

2. Configure environment variables¶

Each example has its own .env. Copy and fill in both:

cp examples/vanilla/.env.example examples/vanilla/.env
cp examples/react/.env.example   examples/react/.env

Variable	Description
`GOOGLE_CLIENT_ID`	OAuth client ID from Google Cloud Console
`GOOGLE_CLIENT_SECRET`	OAuth client secret (never sent to the browser)
`REDIRECT_URI`	Must match what's registered in Google Cloud Console
`JARVIS_URL`	Required — Jarvis API endpoint (e.g. `https://jarvis.host.com`)
`JARVIS_SPEC`	Optional spec override
`PORT`	Express port (default `5500`)

3. Run an example¶

Vanilla JS — floating chat widget, served at http://localhost:5500

npm run example:vanilla

React — useJarvis hook demo with proper cleanup, served at http://localhost:5501

npm run example:react