Developer Documentation

SDK Documentation

A lightweight, drop-in SDK for sending secure session and event data to the Unshared Labs platform. Designed for server environments like Express, Fastify, or Next.js API routes.

Installation

Install the SDK using npm or yarn:

npm install unshared-clientjs-sdk
# or
yarn add unshared-clientjs-sdk

Quick Start

Initialize the client with your API key:

import UnsharedLabsClient from "unshared-clientjs-sdk";

const client = new UnsharedLabsClient({
  apiKey: process.env.UNSHARED_LABS_API_KEY!,
});

API: submitEvent

Sends events to the Unshared Labs platform for analysis:

submitEvent(
  eventType: string,
  userId: string,
  ipAddress: string,
  deviceId: string,
  sessionHash: string,
  userAgent: string,
  clientTimestamp: string,
  eventDetails?: map<String,any> | null
): Promise<any>

Parameters

eventTypestringType of event (e.g., "login", "logout", "pageview")
userIdstringUnique identifier for the user
ipAddressstringClient IP address
deviceIdstringUnique device identifier
sessionHashstringSession identifier hash
userAgentstringBrowser/client user agent string
clientTimestampstringISO 8601 timestamp
eventDetailsMap (optional)Additional event metadata

Example: Express Server

Complete example of tracking login events in an Express.js application:

import express from "express";
import UnsharedLabsClient from "unshared-clientjs-sdk";

const app = express();
app.use(express.json());

const client = new UnsharedLabsClient({
  apiKey: process.env.UNSHARED_LABS_API_KEY!,
});

app.post("/login", async (req, res) => {
  const { userId } = req.body;

  try {
    await client.submitEvent(
      "login",
      userId,
      req.ip,
      req.headers["x-device-id"]?.toString() || "unknown-device",
      req.headers["x-session-hash"]?.toString() || "unknown-session",
      req.headers["user-agent"] || "",
      new Date().toISOString(),
      new Map(Object.entries({"example": true, "source": 'test-server' }))
    );

    res.status(200).json({ message: "Login tracked" });
  } catch (err) {
    res.status(500).json({ error: err instanceof Error ? err.message : err });
  }
});

app.listen(3000, () => console.log("Server running on port 3000"));

Need Help?

Have questions about the SDK or need assistance with integration?

Contact Us