@kiponos/react

Production install

npm install @kiponos/react

Also on GitHub release / monorepo source under sdks/kiponos-react-sdk.

Install

npm install @kiponos/react
# peer: react >= 17 (for hooks/provider); Node >= 18; optional peer: ws

Quick start (Node)

export KIPONOS_ID=…          # Connect UI
export KIPONOS_ACCESS=…
export KIPONOS="['MyApp']['1.0']['Dev']['base']"
# optional: KIPONOS_ENV_FILE=/path/to/dotenv

import { Kiponos } from '@kiponos/react';

// New instance from env
const kip = Kiponos.createFromEnv();
// or Java-style process singleton:
// const kip = Kiponos.createForCurrentTeam();

await kip.connect();
await kip.ensurePath('ui');
await kip.path('ui').set('theme', 'light');
console.log(kip.get('theme', undefined, 'ui'));

kip.afterValueUpdated((e) => console.log(e.key, e.value));

Browser handshake (createFromHandshake)

Do not bake Connect tokens into static HTML. Fetch them over HTTPS, then:

import { Kiponos } from '@kiponos/react';

const hs = await fetch('/api/hevruta/handshake').then((r) => r.json());
const kip = Kiponos.createFromHandshake({
  idToken: hs.idToken,
  accessToken: hs.accessToken,
  profile: hs.profile,
  serverUrl: hs.serverUrl, // same-origin WS proxy if the hub rejects query-auth
  authMode: 'auto',        // query in the browser, headers in Node
});
await kip.connect();

authMode: 'auto' is the default for handshake clients.

React on a server / BFF pattern

Browser SPAs must not embed Connect tokens in the bundle. Pattern:

Browser React  ↔  HTTPS handshake  ↔  Kiponos.createFromHandshake  ↔  hub WS

// Node only — create client once
import { Kiponos, KiponosProvider } from '@kiponos/react';
const client = Kiponos.createForCurrentTeam();
await client.connect();

// Pass client into server-rendered tree, or expose SSE to the SPA
<KiponosProvider client={client}>…</KiponosProvider>

KiponosProvider without client + fromEnv only works in Node (reads env). In the browser, inject client from your backend session or use SSE (see Mirror Phone service).

Env vars

| Variable | Required | Purpose | |----------|----------|---------| | KIPONOS_ID | yes | Connect identity token | | KIPONOS_ACCESS | yes | Connect access token | | KIPONOS | recommended | Profile ['App']['rel']['env']['cfg'] | | KIPONOS_ENV_FILE | no | Dotenv path (e.g. otp-listener.env) | | KIPONOS_SERVER | no | Default wss://kiponos.io/api/io-kiponos-sdk |

Not supported

• Passing tokens into new KiponosClient({ idToken, accessToken }) — throws
• Browser createFromEnv — throws (use BFF)

Tests

npm test          # unit
npm run test:e2e  # live PROD via createFromEnv

Design / QA

• DESIGN.md
• QA_REPORT.md

License

MIT