claviz-liminal-qlik

A Qlik Engine gateway that pools sessions and provides an enigma-compatible Node SDK.

Overview

- One Engine session per userId + appId, shared across callers (in-flight open de-dupe).
- Caches common app objects (objects, fields, variables, measures) to reduce duplicate calls.
- Broadcasts changed (optional layout) and synthetic loading events to all subscribers.
- Node client SDK that exposes enigma-style proxies.

Server

$3

``bash
npm install
npm run build
npm start
`

Defaults:

- HTTP: http://localhost:1337
- Health: GET /health

$3

dotenv-flow loads .env*. startServer options override env.

| Setting | Default | Env | Programmatic |
| --- | --- | --- | --- |
| HTTP port | 1337 | PORT | startServer({ port }) |
| Session idle (ms) | 120000 | SESSION_IDLE_MS | startServer({ sessionIdleMs }) |
| Changed debounce (ms) | 125 | CHANGED_DEBOUNCE_MS | startServer({ changedDebounceMs }) |
| Qlik config provider | - | - | startServer({ getEnigmaConfig }) |
| Qlik connection mode | cloud | QLIK_CONNECTION_MODE | getEnigmaConfig().connectionMode |
| Qlik tenant (cloud) | - | QLIK_TENANT | getEnigmaConfig().qlikTenant |
| Qlik engine URL (certs) | - | QLIK_ENGINE_URL | getEnigmaConfig().qlikEngineUrl |
| Certificates path (certs) | - | QLIK_CERTIFICATES_PATH | getEnigmaConfig().certificatesPath |
| Custom session factory | - | - | startServer({ getEnigmaSession }) |
| Response interceptors | - | - | startServer({ getResponseInterceptors }) |
| Error handler | - | - | startServer({ onError }) |
| Logger | console.log | - | startServer({ logger }) |

Notes:

- In cloud mode, clients must provide a Qlik API token (see Client).
- In certificates mode, clients must provide a Qlik user directory.
- Providing getEnigmaConfig bypasses env-based config for Qlik connection settings.
- logger: null disables logs.

$3

- Sessions are keyed by userId + appId; idle cleanup uses sessionIdleMs.
- If a session is closed or returns NOT_CONNECTED, the gateway marks it dead and rehydrates on the next call or subscription.
- GET /health includes sessionDetails with per-session status (dead/alive, idle time, handles, subscriptions).
- changed can optionally include a layout (see includeLayout in Client options).
- Synthetic loading helps UI state around longer-running calls.
- createSessionObject is cached only when qInfo.qId is provided; cache is per session and cleared by destroySessionObject.

$3

- Alive session: enigma session is open; handles point to live APIs; calls go through normally.
- Dead session: enigma session closed or a call returned NOT_CONNECTED; handles are kept but their APIs are cleared.
- Rehydrate: on the next call/subscribe, the gateway opens a new enigma session, recreates global/app, and rebinds known handles (objects/fields/variables/measures). Unknown handles throw SESSION_CLOSED.
- Idle cleanup: a session is disposed only when it has no subscriptions and has been idle longer than sessionIdleMs (same rule for alive and dead).

Client

$3

`ts
import { QlikGatewayClient } from 'claviz-liminal-qlik/client';

const session = await QlikGatewayClient.connectSession('http://localhost:1337', {
userId: 'user@example.com',
appId: 'YOUR_APP_ID',
token: process.env.QLIK_API_TOKEN,
userDirectory: 'YOUR_USER_DIRECTORY', // certificates mode
});

const app = await (await session.open()).openDoc();
const viz = await app.getObject('YOUR_OBJECT_ID');

viz.on('changed', ({ layout }) => {
// layout is pushed by the server when includeLayout is true
}, { includeLayout: true });

viz.on('loading', ({ active }) => {
// show/hide overlay
});

await session.close();
`

$3

- QlikGatewayClient.connect(url, { timeoutMs?, token?, userDirectory? }) (default timeoutMs is 30000).
- QlikGatewayClient.connectSession(url, { userId, appId, timeoutMs?, token?, userDirectory? }).
- openGlobal/openApp params: { userId, appId, token?, userDirectory? } (token used for Qlik Cloud).
- Subscription options: { includeLayout?, debounceMs? } for changed.
- EnigmaGatewaySession.close()` only disconnects the socket if it owns it.