@paralyn/sdk

The fastest way to add a production AI assistant to your product.

Embed PARALYN's role-aware, streaming generative AI into any React application with a single component. No backend AI work required — your users get a smart, context-aware assistant that knows their role, their data, and what they're allowed to do.

Overview

Ship a production-grade AI assistant to your users in under an hour — without building WebSocket infrastructure, auth flows, or permission systems.

@paralyn/sdk connects your React app to the PARALYN Platform: one component handles streaming responses, role-based permissions, confirmation dialogs, and generative UI surfaces out of the box. Your team writes product logic; PARALYN handles the AI layer.

Key capabilities

| Feature | Description | |---------|-------------| | ParalynWidget | Floating React chat widget with streaming responses | | defineConfig / compileManifest | Declarative workspace configuration | | getGatewayWebSocketUrl | Derive WebSocket URL from your API base | | Web Component | <paralyn-widget> for non-React apps |

Installation

npm install @paralyn/sdk

Peer dependencies: react >=18, react-dom >=18

Get your credentials in 30 seconds

Run this once in your project root — it registers a workspace and writes your credentials to .env automatically:

npx @paralyn/cli init

You'll be prompted for a workspace slug, display name, and email. Your PARALYN_HANDOFF_SECRET and other env vars are written to .env immediately. No dashboard, no manual copy-paste.

Quick start (Next.js)

1. Mint a session token server-side

// app/api/paralyn-session/route.ts
import { NextResponse } from "next/server";

export async function GET() {
  const res = await fetch(`${process.env.PARALYN_API_URL}/api/auth/session`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PARALYN_TENANT_ADMIN_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sub: "user-123",          // your user's stable ID
      workspace: "acme-corp",
      tenant_id: "acme-corp",
      role: "user",
    }),
  });
  const { sessionToken } = await res.json();
  return NextResponse.json({ sessionToken });
}

2. Embed the widget

"use client";

import { ParalynWidget, getGatewayWebSocketUrl } from "@paralyn/sdk";

const API_BASE = process.env.NEXT_PUBLIC_PARALYN_API_URL!;

export function AIChatButton({ sessionToken, userId }: {
  sessionToken: string;
  userId: string;
}) {
  return (
    <ParalynWidget
      apiKey={sessionToken}
      userId={userId}
      userRole="user"
      workspace="acme-corp"
      tenantId="acme-corp"
      context={{ currentPage: "/dashboard" }}
      gatewayWsUrl={getGatewayWebSocketUrl(API_BASE)}
    />
  );
}

Widget props

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiKey | string | ✅ | Short-lived PARALYN access JWT (never a raw API key) | | userId | string | ✅ | Your user's stable ID | | userRole | string | ✅ | "user", "admin", or "developer" | | workspace | string | ✅ | Workspace slug | | tenantId | string | | Defaults to workspace | | context | object | | Extra context merged into every message (page, cart state, etc.) | | gatewayWsUrl | string | | WebSocket endpoint, defaults to derived URL | | createWebSocket | function | | Override socket constructor (useful for testing) | | className | string | | Additional CSS classes |

Workspace config

import { defineConfig, compileManifest } from "@paralyn/sdk";

const config = defineConfig({
  workspace: "acme-corp",
  roles: ["user", "admin"],
  actions: [
    {
      name: "refund_order",
      roles: ["admin"],
      endpoint: "/paralyn/actions/refund",
      requiresConfirmation: true,
      confirmationMessage: "This will issue a full refund. Continue?",
    },
    {
      name: "track_order",
      roles: ["user", "admin"],
    },
  ],
});

// Compile to manifest JSON for the API gateway
const manifest = compileManifest(config);

Web Component (vanilla JS / non-React)

import { registerParalynWebComponent } from "@paralyn/sdk";
registerParalynWebComponent();

<paralyn-widget
  api-key="eyJ..."
  user-id="user-123"
  user-role="user"
  workspace="acme-corp"
  tenant-id="acme-corp"
  gateway-ws-url="wss://paralyn-api.onrender.com/ws"
  context-json='{"currentPage":"/home"}'
></paralyn-widget>

Wire protocol

The widget communicates over NDJSON WebSocket.

Server → Client

{ "type": "token",          "value": "Hello" }
{ "type": "error",          "code": "permission_denied" }
{ "type": "pending_action", "id": "a1", "requiresConfirmation": true, "message": "Refund $49?" }
{ "type": "ui_surface",     "id": "s1", "layout": "table", "title": "Orders", "data": [...] }

Client → Server

{ "type": "hello",          "apiKey": "...", "userId": "...", "userRole": "...", "context": {} }
{ "type": "user_message",   "text": "...", "context": { "conversationHistory": [] } }
{ "type": "action_confirm", "id": "a1" }
{ "type": "action_cancel",  "id": "a1" }
{ "type": "ping" }

The widget reconnects automatically with exponential backoff and sends a heartbeat ping every 30 seconds.

Security

• Never pass PARALYN_TENANT_ADMIN_TOKEN or workspace API keys to the browser.
• Always mint session tokens server-side and pass them as apiKey.
• Tokens are short-lived (15 minutes by default). The widget will display an error if the session expires.

Related packages

| Package | Description | |---------|-------------| | @paralyn/identity | Handoff tokens and session JWT utilities |

License

AfriIntelligence — © PARALYN. All rights reserved.