Lumina JavaScript SDK

Production-grade JavaScript SDK with:

• Retry + exponential backoff
• Batch sending (/api/v1/events/batch)
• Offline queue persistence (browser localStorage / Node disk)
• Persistent device id
• Error model (LuminaHttpError, LuminaTransportError)
• Event hooks (on("CRITICAL", ...))
• Browser auto mouse tracking (autoTrackMouse)

Structure

sdk/javascript/
  index.js
  queue.js
  utils.js
  lumina-client.js  # backward-compatible shim

Quick Start

Install:

npm i @lumina-core/core-sdk

const Lumina = require("@lumina-core/core-sdk");

const lumina = new Lumina({
  apiKey: "lumina_test",
  traderId: "TR_001",
  orgId: "org_abc123",
  baseUrl: "http://localhost:5000",
  flushInterval: 2000,
  maxBatch: 10,
});

lumina.on("CRITICAL", (payload) => {
  console.log("CRITICAL", payload);
});

lumina.track({
  type: "click",
  reactionTime: 200,
  rapidReentry: true,
});

async function run() {
  const state = await lumina.getState();
  console.log(state);
  await lumina.shutdown({ flush: true });
}

run().catch(console.error);

Notes

• orgId is optional but recommended for org-scoped SDK keys.
• When orgId is set, SDK sends x-org-id automatically.

Release Helpers

From repository root:

./sdk/release/bump-sdk-version.ps1 -Version 0.2.0
./sdk/release/run-sdk-release-checks.ps1 -SkipPython
./sdk/release/publish-sdk.ps1 -PublishJavaScript -DryRun

Browser Auto Tracking

await lumina.autoTrackMouse({ emitIntervalMs: 2000 });
// alias
await lumina.auto_track_mouse({ emitIntervalMs: 2000 });

Error Handling

const {
  LuminaHttpError,
  LuminaTransportError,
} = require("./index");

try {
  await lumina.getState();
} catch (error) {
  if (error instanceof LuminaHttpError) {
    console.error("HTTP", error.status, error.payload);
  } else if (error instanceof LuminaTransportError) {
    console.error("Network", error.message);
  } else {
    console.error(error);
  }
}