@openelan/elan-web-sdk

Browser / Next.js SDK for Elan auth and integration APIs.

Installation

npm install @openelan/elan-web-sdk
# or
pnpm add @openelan/elan-web-sdk

Initialize

import { initializeApp } from "@openelan/elan-web-sdk";

const app = initializeApp({
  baseUrl: "https://api.elan.ai",
  realtimeUrl: "https://realtime.elan.ai",
  authClientId: "cli_auth123",   // used for auth calls and WebSocket auth context
  swarmClientId: "cli_swarm456", // sent as x-swarm-client-id on integration API requests
});

authClientId and swarmClientId are separate required fields. There is no shared clientId fallback — you must provide both explicitly.

Auth

Get an auth instance with getAuth(app).

import { getAuth } from "@openelan/elan-web-sdk";

const auth = getAuth(app);

Register (onboarding)

auth.registerUser(params) creates a user for your OAuth client and sends a verification email.

const result = await auth.registerUser({
  email: "[email protected]",
  password: "Secure1234",
  displayName: "Jane Doe",
  actionUrl: "https://yourapp.com/email-verified",
  // clientId is optional here; defaults to authClientId from initializeApp config
});

actionUrl and the browser Origin must be in the client's authorizedDomains.

Verify email

Users click the email link directly. For programmatic verification:

await auth.verifyClientEmail(tokenFromQueryParam);

Throws ElanAuthError if the token is invalid or expired.

Sign in

auth.signInWithEmail(email, password, opts?) signs in a client-bound user.

const { user, accessToken, refreshToken } = await auth.signInWithEmail(
  "[email protected]",
  "Secure1234",
);

User state

auth.getCurrentUser(accessToken) returns the current user's profile. Also available as auth.introspectSession(accessToken).

const user = await auth.getCurrentUser(accessToken);
console.log(user.email, user.displayName);

auth.onUserChange(listener) subscribes to user state changes. Returns an unsubscribe function.

const unsubscribe = auth.onUserChange((user) => {
  if (user) {
    console.log("Signed in:", user.email);
  } else {
    console.log("Signed out");
  }
});

// later
unsubscribe();

Password and metadata

auth.changePassword(currentPassword, newPassword) changes the signed-in user's password.

await auth.changePassword("OldPass1", "NewPass2");

auth.forgetPassword(email, action) initiates a password-reset flow by sending a reset email.

await auth.forgetPassword("[email protected]", { actionUrl: "https://yourapp.com/reset-password" });

auth.resetPassword(code, newPassword) completes the reset using the code from the email link.

await auth.resetPassword(codeFromQueryParam, "NewSecurePass3");

auth.setMetadata(metadata) updates arbitrary key/value metadata on the signed-in user.

await auth.setMetadata({ theme: "dark", onboardingComplete: "true" });

Messaging

Get an integration instance with getIntegration(app). The user must be signed in.

import { getIntegration } from "@openelan/elan-web-sdk";

const integration = getIntegration(app);

Create a session

const { sessionId } = await integration.createSession();

Send a message

await integration.sendMessage(sessionId, "Hello agent!");

Send and wait for a reply

integration.sendSync(messageOrParts, opts?) sends a message and returns the completed response.

const reply = await integration.sendSync("What is 6 x 7?");
console.log(reply.finalText);

Error handling

Auth methods throw ElanAuthError; integration methods throw ElanIntegrationError; realtime connection pre-condition failures throw ElanRealtimeError.

import {
  ElanAuthError,
  ElanAuthErrorCode,
  ElanIntegrationError,
  ElanRealtimeError,
} from "@openelan/elan-web-sdk";

try {
  await auth.signInWithEmail(email, password);
} catch (err) {
  if (err instanceof ElanAuthError) {
    if (err.code === ElanAuthErrorCode.InvalidCredentials) {
      console.error("Wrong email or password");
    }
  }
}

try {
  await integration.sendMessage(sessionId, "Hi");
} catch (err) {
  if (err instanceof ElanIntegrationError) {
    console.error(err.message);
  }
}

try {
  realtime.connect({ userId: currentUser.uid });
} catch (err) {
  if (err instanceof ElanRealtimeError) {
    console.error("Realtime connection failed:", err.message);
  }
}

Common ElanAuthError codes: invalid-credentials, email-not-verified, email-already-in-use, session-expired, permission-denied, network-error, timeout, unknown.

Realtime

Get a realtime client with getRealtime(app). The user must be signed in (IAM cookies are forwarded automatically).

import { getRealtime } from "@openelan/elan-web-sdk";

const realtime = getRealtime(app);
// The default clientId for the WS connection comes from authClientId.

// Register listeners before connecting
realtime.onOpen((ack) => {
  console.log("Connected as", ack.userId, "on client", ack.clientId);
});

realtime.onMessage((msg) => {
  console.log("Received message:", msg);
});

realtime.onError((err) => {
  if (err.type === "server") {
    console.error("Server error:", err.code);
  } else {
    console.error("Transport error");
  }
});

realtime.onClose((code, reason) => {
  console.log("Disconnected", code, reason);
});

// Connect — userId is required; clientId falls back to app config
realtime.connect({ userId: currentUser.uid });

// Optionally scope to a session
realtime.connect({
  userId: currentUser.uid,
  sessionId: "sess_abc123",
});

// Disconnect when done
realtime.disconnect();

realtimeUrl derivation

The SDK accepts http:// or https:// base URLs and converts them to ws:// / wss:// automatically:

| Config value | WS URL used | |---|---| | https://realtime.elan.ai | wss://realtime.elan.ai | | http://localhost:8081 | ws://localhost:8081 |