Classes

The Orga Node SDK exports a single main class — OrgaAI — that handles all server‑side interactions with the Orga Cloud API.

This class allows you to safely exchange your server API key for short‑lived credentials
that your frontend apps (React, React Native, or others) can use for real‑time audio and video sessions.

`OrgaAI` Class

The core class used to communicate with Orga’s backend and generate secure ephemeral credentials.


import { OrgaAI } from "@orga-ai/node";
 
const orga = new OrgaAI({
  apiKey: process.env.ORGA_API_KEY!,
  userEmail: process.env.USER_EMAIL!, // optional soon
  timeout: 10000,
  debug: true,
});

Constructor


new OrgaAI(config: OrgaAIConfig)

Parameter	Type	Required	Description
`apiKey`	`string`	✅	Your permanent Orga API key (server‑side only).
`userEmail`	`string`	✅ (temporary)	Used for auditing; will become optional in an upcoming release.
`baseUrl`	`string`	❌	Override base API endpoint (defaults to `https://api.orga-ai.com`).
`timeout`	`number`	❌	Timeout in milliseconds (default: `10000`).
`debug`	`boolean`	❌	Enables debug logging in node console.

Properties

Property	Type	Description
`apiKey`	`string`	The server’s Orga API key used for authenticated requests.
`userEmail`	`string`	Email identifier for API tracking (required now; optional soon).
`timeout`	`number`	Request timeout for all SDK HTTP calls.
`debug`	`boolean`	Enables verbose logging of requests and responses.

Methods

`getSessionConfig()`

Fetches both an ephemeral authentication token and a list of ICE (STUN/TURN) servers.
This is the only method you typically need to expose in your backend endpoint.


const creds = await orga.getSessionConfig();
 
console.log(creds);
/*
{
  ephemeralToken: "eyJhbGciOi...",
  iceServers: [
    { urls: "stun:stun1.l.google.com:19302" },
    {
      urls: ["turn:turn.orga-ai.com:3478"],
      username: "6b4c...",
      credential: "0433..."
    }
  ]
}
*/

Returns	Type	Description
`Promise<SessionConfig>`	`{ ephemeralToken: string; iceServers: IceServer[] }`	Session configuration object passed to client SDKs.

💡 Usage Tip: getSessionConfig() automatically calls internal methods fetchEphemeralToken() and fetchIceServers() in sequence.
It also handles error handling.

`fetchEphemeralToken()`

internal

Requests a new ephemeral token using your API key.


const token = await orga.fetchEphemeralToken();

Returns	Type	Description
`Promise<string>`	The short‑lived JWT-style token issued by Orga Cloud.

`fetchIceServers()`

internal

Retrieves TURN/STUN server list used for WebRTC connection establishment.


const iceServers = await orga.fetchIceServers(token);

Parameter	Type	Description
`token`	`string`	The ephemeral token to authenticate this request.
Returns	`Promise<IceServer[]>`	List of ICE server objects for WebRTC configuration.

Error Handling

All SDK methods throw typed errors extending from the OrgaAIError base class.

Error Class	Description	Typical Trigger
`OrgaAIError`	Generic SDK or configuration error.	Missing API key, malformed config.
`OrgaAIAuthenticationError`	Authentication failure.	Invalid API key or email.
`OrgaAIServerError`	Remote API responded with error status code.	4xx/5xx responses.

Example:


try {
  const creds = await orga.getSessionConfig();
  console.log("Ephemeral token:", creds.ephemeralToken);
} catch (error) {
  if (error instanceof OrgaAIAuthenticationError) {
    console.error("Invalid API credentials");
  } else if (error instanceof OrgaAIServerError) {
    console.error("Orga Cloud unavailable:", error.message);
  } else {
    console.error("Unexpected error:", error);
  }
}

Debug Mode

Enable debug: true to trace SDK operations.


const orga = new OrgaAI({
  apiKey: process.env.ORGA_API_KEY!,
  userEmail: process.env.USER_EMAIL!,
  debug: true,
});

Logs output:


[OrgaAI] Fetching session config...
[OrgaAI] Fetched ephemeral token: eyJhbGc...
[OrgaAI] Fetched ICE servers: 3

Example (Full Express Integration)

server.ts


import express from "express";
import { OrgaAI } from "@orga-ai/node";
 
const app = express();
const orga = new OrgaAI({
  apiKey: process.env.ORGA_API_KEY!,
  userEmail: process.env.USER_EMAIL!,
  debug: true,
});
 
app.get("/api/orga-client-secrets", async (_req, res) => {
  try {
    const creds = await orga.getSessionConfig();
    res.json(creds);
  } catch (err) {
    console.error("Error generating credentials", err);
    res.status(500).json({ error: "Internal server error" });
  }
});
 
app.listen(5000, () => console.log("Server running on port 5000"));

Client SDK Config Notes

When integrating with client SDKs:

fetchSessionConfig (recommended):


OrgaAI.init({
  fetchSessionConfig: async () => {
    const res = await fetch("/api/orga-client-secrets", {
      headers: { Authorization: `Bearer ${user.accessToken}` },
    });
    return await res.json(); // { ephemeralToken, iceServers }
  },
});
Implemented by the client developer — allows you to include custom auth headers or middleware.

✅ Necessary if your backend route requires authentication.

sessionConfigEndpoint:


OrgaAI.init({
  sessionConfigEndpoint: "http://localhost:5000/api/orga-client-secrets",
});

Invoked automatically by the client SDK — convenient for demos or open endpoints, but bypasses custom auth layers.

Not suitable for endpoints with authorization logic.

Next Steps

Types → Explore available configuration and response types.
Errors → Learn how to handle exceptions gracefully.
Troubleshooting → Troubleshooting guide.